Texas Instruments TMS320 Series User Manual Download

Page: 1 / 288

TMS320 DSP/BIOS v5.40

User’s Guide

Literature Number: SPRU423G

April 2009

Summary of Contents for TMS320 Series

Page 1: ...TMS320 DSP BIOS v5 40 User s Guide Literature Number SPRU423G April 2009 ...

Page 2: ...e TI is not responsible or liable for any such statements TI products are not authorized for use in safety critical applications such as life support where a failure of the TI product would reasonably be expected to cause severe personal injury or death unless officers of the parties have executed an agreement specifically governing such use Buyers represent that they have all necessary expertise ...

Page 3: ... familiar with the TMS320 DSP BIOS API Reference Guide for your platform The API reference guide is a companion volume to this user s guide Notational Conventions This document uses the following conventions Program listings code examples and interactive displays are shown in a special typeface Examples use a bold version of the special typeface for emphasis interactive displays use a bold version...

Page 4: ... Instruments The following sources describe TMS320 devices and related support tools To obtain a copy of any of these TI documents visit the Texas Instruments website at www ti com TMS320C28x DSP BIOS API Reference literature number SPRU625 TMS320C5000 DSP BIOS API Reference literature number SPRU404 TMS320C6000 DSP BIOS API Reference literature number SPRU403 describes the DSP BIOS API functions ...

Page 5: ...ource code for the C55x generation of devices TMS320C6000 Optimizing C Compiler User s Guide literature number SPRU187 describes the C6000 C C compiler and the assembly optimizer This C C compiler accepts ANSI standard C C source code and produc es assembly language source code for the C6000 generation of devices The assembly optimizer helps you optimize your assembly code TMS320C55x Programmer s ...

Page 6: ...es in Computer Science by M Ben Ari published by Prentice Hall ISBN 013711821X May 1990 American National Standard for Information Systems Programming Language C X3 159 1989 American National Standards Institute ANSI standard for C out of print Trademarks MS DOS Windows and Windows NT are trademarks of Microsoft Corporation The Texas Instruments logo and Texas Instruments are registered trademarks...

Page 7: ... Applications 2 2 2 2 Converting CCSv3 3 Projects to CCSv4 Projects 2 10 2 3 Configuring DSP BIOS Applications Statically 2 11 2 4 Creating DSP BIOS Objects Dynamically 2 16 2 5 Files Used to Create DSP BIOS Programs 2 18 2 6 Using Makefiles to Build Applications 2 20 2 7 Using DSP BIOS with the Run Time Support Library 2 22 2 8 DSP BIOS Startup Sequence 2 24 2 9 Using C with DSP BIOS 2 28 2 10 Us...

Page 8: ...ices 5 12 5 3 Queues 5 15 6 Input Output Methods 6 1 This chapter provides an overview of DSP BIOS data transfer methods and discusses pipes in particular 6 1 I O Overview 6 2 6 2 Comparing Pipes and Streams 6 3 6 3 Comparing Driver Models 6 5 6 4 Data Pipe Manager PIP Module 6 8 6 5 Message Queues 6 15 6 6 Host Channel Manager HST Module 6 27 6 7 I O Performance Issues 6 28 7 Streaming I O and De...

Page 9: ...ents ix Contents 7 11 Device Driver Initialization 7 33 7 12 Opening Devices 7 34 7 13 Real Time I O 7 38 7 14 Closing Devices 7 41 7 15 Device Control 7 43 7 16 Device Ready 7 43 7 17 Types of Devices 7 46 ...

Page 10: ...on Scenario 4 10 4 3 The Interrupt Sequence in Debug Halt State 4 15 4 4 The Interrupt Sequence in the Run time State 4 17 4 5 Software Interrupt Manager 4 27 4 6 SWI Properties Dialog Box 4 28 4 7 Using SWI_inc to Post an SWI 4 32 4 8 Using SWI_andn to Post an SWI 4 33 4 9 Using SWI_or to Post an SWI 4 34 4 10 Using SWI_dec to Post an SWI 4 35 4 11 Execution Mode Variations 4 42 4 12 Trace from E...

Page 11: ...sor 6 24 7 1 Device Independent I O in DSP BIOS 7 2 7 2 Device Driver and Stream Relationship 7 4 7 3 How SIO_get Works 7 9 7 4 Output Trace for Example 7 5 7 12 7 5 Results for Example 7 6 7 14 7 6 The Flow of Empty and Full Frames 7 17 7 7 Sine Wave Output for Example 7 9 7 21 7 8 Flow of DEV_STANDARD Streaming Model 7 38 7 9 Placing a Data Buffer to a Stream 7 39 7 10 Retrieving Buffers from a ...

Page 12: ... 2 3 Stack Modes on the C5500 Platform 2 27 3 1 Examples of Code size Increases Due to an Instrumented Kernel 3 16 3 2 TRC Constants 3 27 3 3 Variables that can be Monitored with HWI 3 35 3 4 STS Operations and Their Results 3 36 4 1 Comparison of Thread Characteristics 4 5 4 2 Thread Preemption 4 9 4 3 SWI Object Function Differences 4 31 4 4 CPU Registers Saved During Software Interrupt 4 36 7 1...

Page 13: ...SR on C6000 Platform 4 23 4 4 HWI Example on C55x Platform 4 23 4 5 HWI Example on C28x Platform 4 24 4 6 Creating a Task Object 4 45 4 7 Time Slice Scheduling 4 46 4 8 Creating and Deleting a Semaphore 4 59 4 9 Setting a Timeout with SEM_pend 4 60 4 10 Signaling a Semaphore with SEM_post 4 60 4 11 SEM Example Using Three Writer Tasks 4 61 4 12 Creating a Mailbox 4 65 4 13 Reading a Message from a...

Page 14: ...lementing the Issue Reclaim Streaming Model 7 8 7 5 Basic SIO Functions 7 10 7 6 Adding an Output Stream to Example 7 5 7 13 7 7 Using the Issue Reclaim Model 7 15 7 8 Opening a Pair of Virtual Devices 7 16 7 9 Data Exchange Through a Pipe Device 7 19 7 10 Using SIO_ctrl to Communicate with a Device 7 22 7 11 Changing Sample Rate 7 22 7 12 Synchronizing with a Device 7 22 7 13 Indicating That a St...

Page 15: ...atures for a Terminating Device 7 36 7 29 Template for Dxx_issue for a Typical Terminating Device 7 40 7 30 Template for Dxx_reclaim for a Typical Terminating Device 7 40 7 31 Closing a Device 7 41 7 32 Making a Device Ready 7 43 7 33 SIO_Select Pseudocode 7 44 ...

Page 16: ...xvi ...

Page 17: ...e scheduling and synchronization host to target communication or real time instrumentation DSP BIOS provides preemptive multi threading hardware abstraction real time analysis and configuration tools 1 1 DSP BIOS Features and Benefits 1 2 1 2 DSP BIOS Components 1 4 1 3 Naming Conventions 1 9 1 4 For More Information 1 14 Topic Page ...

Page 18: ...d CPU requirements has been kept to a minimum Instead the API reference documentation specifies constraints for calling API functions It is the responsibility of the application developer to meet these constraints In addition the DSP BIOS API provides many options for program development A program can dynamically create and delete objects that are used in special situations The same program can us...

Page 19: ...allow real time monitoring of program behavior DSP BIOS provides a standard API This allows DSP algorithm developers to provide code that can be more easily integrated with other program functions DSP BIOS is integrated within the Code Composer Studio v4 IDE requires no runtime license fees and is fully supported by Texas Instruments DSP BIOS is a key a component of TI s eXpressDSPTM real time sof...

Page 20: ...ols These tools in Code Composer Studio let you test the program on the target device while monitoring CPU load timing logs thread execution and more Thread refers to any thread of execution hardware interrupt software interrupt task or idle function The sections that follow provide an overview of these DSP BIOS components Target Host Target hardware DSP application program DSP Code Composer Studi...

Page 21: ...vide C callable interfaces Most C callable interfaces can also be called from assembly language provided that C calling conventions are followed Some of the C interfaces are actually C macros and therefore cannot be used when called from assembly language Refer to the TMS320 DSP BIOS API Reference Guide for your platform for details Table 1 1 DSP BIOS Modules Module Description ATM Atomic function...

Page 22: ...r s Guide SPRU007 for details Graphically You can view configurations in read only mode with the DSP BIOS Configuration Tool a graphical editor that functions as a macro recorder for scripts The interface is similar to that of the Windows Explorer The script is shown in the right pane as you create it You can set a wide range of parameters used by DSP BIOS at run time The objects you create are us...

Page 23: ... executable program image Alternately a DSP BIOS program can create and delete certain objects at run time In addition to minimizing the target memory footprint by eliminating run time code and optimizing internal data structures creating static objects detects errors earlier by validating object properties before program compilation See the DSP BIOS online help and Section 2 3 Configuring DSP BIO...

Page 24: ...analysis capabilities are provided Program tracing Displaying events written to target logs reflecting dynamic control flow during program execution Performance monitoring Tracking summary statistics that reflect use of target resources such as processor load and timing File streaming Binding target resident I O objects to host files When used in tandem with other debugging capabilities of Code Co...

Page 25: ... that module s interface xxx h DSP BIOS API header files for C programs Your C source files should include std h and the header files for any modules the C functions use xxx h DSP BIOS API header files for assembly programs Assembly source files should include the appropriate xxx h header file for any module the assembly source uses For example hwi h62 This file contains macro definitions specific...

Page 26: ...of the DSP BIOS API also includes several built in functions that are run by various built in objects Here are some examples CLK_F_isr Run by an HWI object to provide the low resolution CLK tick PRD_F_tick Run by the PRD_clock CLK object to manage PRD_SWI and system tick PRD_F_swi Triggered by PRD_tick to run the PRD functions _KNL_run Run by the lowest priority SWI object KNL_swi to run the task ...

Page 27: ...n most cases the standard DSP BIOS types are uppercase versions of the corresponding C types The data types shown in Table 1 2 are defined in the std h header file Table 1 2 DSP BIOS Standard Data Types Additional data types are defined in std h but are not used by DSP BIOS APIs In addition the standard constant NULL 0 is used by DSP BIOS to signify an empty pointer value The constants TRUE 1 and ...

Page 28: ...to declare DSP BIOS objects 1 3 5 Memory Segment Names The memory segment names used by DSP BIOS are described in Table 1 3 You can change the origin size and name of most default memory segments in the configuration Table 1 3 Memory Segment Names Memory Segment Names C55x Platform Memory Segment Names C6000 EVM Platform Memory Segment Names C6000 DSK Platform Segment Description IDATA Primary blo...

Page 29: ... code memory FLASH Internal flash program memory VECT Interrupt vector table when VMAP 0 VECT1 Interrupt vector table when VMAP 1 OTP One time programmable memory via flash registers H0SARAM Internal program RAM L0SARAM Internal data RAM M1SARAM Internal user and task stack RAM Sections Segment System stack Memory stack System Stack Memory sysstack DATA BIOS Kernel State Memory sysdata DATA BIOS O...

Page 30: ...System stack memory stack IDRAM Application constants memory const IDRAM Program memory text IPRAM Data memory data IDRAM Startup code memory sysinit IPRAM C initialization records memory cinit IDRAM Uninitialized variables memory bss IDRAM Sections Segment System stack memory stack M1SARAM Program memory text IPROG Data memory data IDATA Applications constants memory const IDATA Startup code memo...

Page 31: ...2 Converting CCSv3 3 Projects to CCSv4 Projects 2 10 2 3 Configuring DSP BIOS Applications Statically 2 11 2 4 Creating DSP BIOS Objects Dynamically 2 16 2 5 Files Used to Create DSP BIOS Programs 2 18 2 6 Using Makefiles to Build Applications 2 20 2 7 Using DSP BIOS with the Run Time Support Library 2 22 2 8 DSP BIOS Startup Sequence 2 24 2 9 Using C with DSP BIOS 2 28 2 10 User Functions Called ...

Page 32: ...rm type in the Project Type field For example you might select C6000 Then click Next d Click Next in the Additional Project Settings page e In the CCS Project Settings page select the Device Variant for your desired platform For example you might select Generic C64x Device Depending on your device you might also need to adjust the Device Endianness and Runtime Support Library settings f In the Tar...

Page 33: ...u disable RTDX you will not be able to view real time analysis RTA data The ROV tool provides stop mode access to data and is supported even if RTDX is disabled See Section 3 8 TSK Manager Tasks are threads that allow yielding and can use thread synchronization objects such as semaphores Most applications use tasks but some may only use hardware and software interrupts See Section 4 4 e After you ...

Page 34: ...includes hellocfg h which would be generated from a configuration file called hello tcf If your configuration file has a different name you should modify the include statement For example if your configuration file is hellobios5 tcf modify the hello c file to include the hellobios5cfg h file 4 Create a target configuration for the CCS project to use when building as follows a Choose File New Targe...

Page 35: ...es where you want to stop For example in hello c you might set a breakpoint on the return line c Choose Tools ROV to open the Runtime Object Viewer which allows you to view the state of objects created with RTSC packages such as DSP BIOS d Expand the hierarchy in the ROV tool so you can select the trace LOG e Choose Target Run or click the Run icon to run to the breakpoint f The information for th...

Page 36: ... for which you can set properties In addition most modules let you create object instances for which you can set properties In the DSP BIOS Configuration Tool you can perform the following actions Create and name objects See Section 2 1 1 1 Set global properties for the application module manager properties and object properties See Section 2 1 1 2 Set priorities for software interrupts and tasks ...

Page 37: ...s dialog 3 When you have finished setting properties click OK 2 1 1 3 Setting Priorities in the Configuration Tool You can set priority levels for SWI or TSK object Likewise you can set the execution order of CLK PRD IDL and HOOK objects To set such priorities or execution orders follow these steps 1 In the Configuration Tool highlight the manager whose priorities or order you want to set 2 Notice...

Page 38: ...the tcf configuration file This file has the filename tcf_file cfg h For example if the tcf file for a project is hello tcf the include statement would be as follows include hellocfg h The main function simply prints a message to a log using the LOG_printf API This API is very efficient To reduce execution time LOG_printf just passes raw data to the host PC formatting is done on the PC main Void m...

Page 39: ...tatic objects for your program to use This can be done using the DSP BIOS Configuration Tool or the Tconf scripting language 2 Write a framework for your program You can use C C assembly or a combination of the languages 3 Add files to your project and compile and link the program using Code Composer Studio 4 Test program behavior using a simulator or initial hardware and the DSP BIOS analysis too...

Page 40: ...SP BIOS application programcfg cmd is your project s linker command file This file already includes directives for the linker to use the appropriate libraries e g bios a62 rtdx lib rts64plus lib so you do not need to add any of these library files to your project For most DSP BIOS applications the generated linker command file programcfg cmd suffices to describe all memory segments and allocations...

Page 41: ...n reload the script into the DSP BIOS Configuration Tool for further graphical editing There are certain restrictions on graphical editing after you have edited a script or started a new configuration session 2 3 2 When to Use a Text Editor Use a text editor to modify a script if you want the following advantages If you want a script to use branching looping and other constructs If you want to cre...

Page 42: ...SP BIOS objects 2 3 3 1 Small and Large Model Issues for C6000 Although DSP BIOS itself is compiled using the small model you can compile DSP BIOS applications using either the C6000 compiler s small model or any variation of the large model See the TMS320C6000 Optimizing Compiler User s Guide In fact you can mix compilation models within the application code provided all global data that is acces...

Page 43: ...tes in length Global data therefore can be accessed with a single instruction like the following LDW DP _x A0 load _x into A0 DP B14 Since objects created statically are not placed in the bss section you must ensure that application code compiled with the small model references them correctly There are three ways to do this Method Declare objects with far Use global object pointers Objects adjacen...

Page 44: ...example extern PIP_Obj inputObj input MUST be a global variable PIP_Obj input inputObj if PIP_getReaderNumFrames input Declaring and initializing the global pointer consumes an additional word of data to hold the 32 bit address of the object Also if the pointer is a static or automatic variable this technique fails The following code does not operate as expected when compiled using the small model...

Page 45: ...instruction to load the data For example MVKL _x A0 move low 16 bits of _x s address into A0 MVKH _x A0 move high 16 bits of _x s address into A0 LDW A0 A0 load _x into A0 Application code compiled with any of the large model variants is not affected by the location of static objects If all code that directly references statically created objects is compiled with any large model option code can re...

Page 46: ...an dramatically reduce the size of your application program Improved run time performance In addition to saving code space avoiding dynamic creation of objects reduces the time your program spends performing system setup Creating objects statically has the following limitations Static objects are created whether or not they are needed You may want to create objects dynamically if they will be used...

Page 47: ...reate is shown in Example 2 1 Example 2 1 Creating and Referencing Dynamic Objects The XXX_create function passes back a handle that is an address to the task s object This handle is can then be passed as an argument when referencing for example deleting the object as shown in Example 2 2 Objects created with XXX_create are deleted by calling the function XXX_delete This frees the object s interna...

Page 48: ...P BIOS program tcf The Tconf script that generates the configuration files when run This is the source file for the configuration This is the file you add to a Code Composer Studio project to make the configuration part of the application asm Optional assembly source file s One of these files can contain an assembly language function called _main as an alternative to using a C or C function called...

Page 49: ...der of the project list where program is the configuration file name and 62 is replaced by 28 55 or 64 as appropriate for your platform programcfg cmd Linker command file for DSP BIOS objects This file defines DSP BIOS specific link options and object names and generic data sections for DSP programs such as text bss data etc programcfg h Includes DSP BIOS module header files and declares external ...

Page 50: ... makefile In the following example the C source code file is volume c additional assembly source is in load asm and the configuration file is volume cdb This makefile is for use with gmake which is included with the Code Composer Studio software A typical makefile for compiling and linking a DSP BIOS program is shown in Example 2 3 Unlike the Code Composer Studio project makefiles allow for multip...

Page 51: ...ios include c55rules mak Compiler assembler and linker options g enable symbolic debugging CC55OPTS g AS55OPTS q quiet run LD55OPTS q Every DSP BIOS program must be linked with PROG cfg o55 object resulting from assembling PROG cfg s55 PROG cfg cmd linker command file generated by the Configuration Tool If additional linker command files exist PROG cfg cmd must appear first PROG volume OBJS PROG c...

Page 52: ...same functionality found in the run time support library the DSP BIOS linker command file includes a special version of the run time support library called rtsbios that does not include the files shown in Table 2 2 Table 2 2 Files Not Included in rtsbios In many DSP BIOS projects it is necessary to use the x linker switch in order to force the rereading of libraries For example if printf reference...

Page 53: ...application but call another run time support function which references one or more of them add u _symbol for example u _malloc to your linker options The u linker option introduces a symbol such as malloc as an unresolved symbol into the linker s symbol table This causes the linker to resolve the symbol from the DSP BIOS library rather than the run time support library If in doubt you can examine...

Page 54: ... and the global page pointer B14 are set up to point to the end of the stack section and the beginning of bss respectively Control registers such as AMR IER and CSR are also initialized 2 Initialize the bss from the cinit records Once the stacks are set up the initialization routine is called to initialize the variables from the cinit records 3 Call BIOS_init to initialize the modules used by the ...

Page 55: ...se the C compiler adds an underscore prefix to function names this can be a C or C function called main or an assembly function called _main Since neither hardware nor software interrupts are enabled yet you can take care of initialization procedures for your own application such as calling your own hardware initialization routines from the main routine Your main function can enable individual int...

Page 56: ...orever At this point hardware and software interrupts can occur and preempt idle execution Since the idle loop manages communication with the host data transfer between the host and the target can now take place 2 8 1 Advanced Startup C5500 Platform Only On the C5500 platform the architecture allows the software to reprogram the start of the vector tables 256 bytes in overall length by setting the...

Page 57: ...PU Reference Guide Table 2 3 Stack Modes on the C5500 Platform In addition the DSP BIOS configuration should set the Stack Mode property of the HWI Manager to match the mode used by the application See the TMS320C5000 DSP BIOS API Reference Guide for details Stack Mode Description Reset Vector Settings 2x16 Fast Return SP SSP independent RETA CFCT used for fast return functionality XX00 XXXX 24 bi...

Page 58: ...ned by the run time support library not the DSP BIOS library Since the DSP BIOS library is searched first some applications can result in a linker error stating that there are undefined symbols that were first referenced within the rtsbios the run time support library This linker error is avoided by using the x linker option which forces libraries to be searched again in order to resolve undefined...

Page 59: ... can be called from the configuration Default parameters is a C feature that is not available for functions called from the configuration C allows you to specify default values for formal parameters within the function declaration However a function called from the configuration must provide parameter values If no values are specified the actual parameter values are undefined 2 9 3 Calling Class M...

Page 60: ...an be called from different DSP BIOS threads tasks software interrupts and hardware interrupts For example memory allocation APIs such as MEM_alloc and MEM_calloc cannot be called from within the context of a software interrupt Thus if a particular class is instantiated by a software interrupt its constructor must avoid performing memory allocation Similarly it is important to keep in mind the tim...

Page 61: ... the C6x and C55x platforms all user functions called by DSP BIOS objects need to conform to C compiler register conventions for their respective platforms This applies to functions written both in C and assembly languages The compiler distinguishes between C and assembly functions by assuming that all C function names are preceded by an underscore and assembly function names are not preceded by a...

Page 62: ...ns such as CLK_gethtime and CLK_getltime should not be called from main because the timer is not running HWI_disable and HWI_enable should not be called because hardware interrupts are not globally enabled Potentially blocking calls such as SEM_pend or MBX_pend should not be called from main because the scheduler is not initialized Scheduling calls such as TSK_disable TSK_enable SWI_disable or SWI...

Page 63: ...ct on the application s real time performance Topic Page 3 1 An Overview of Real Time Analysis 3 2 3 2 Real Time Analysis Tools in CCStudio v4 x 3 3 3 3 Runtime Object Viewer ROV 3 10 3 4 Instrumentation Performance 3 15 3 5 Instrumentation APIs 3 18 3 6 Implicit DSP BIOS Instrumentation 3 29 3 7 Instrumentation for Field Testing 3 38 3 8 Real Time Data Exchange 3 38 ...

Page 64: ... you to monitor real time systems as they run This real time monitoring data lets you view the real time system operation so that you can effectively debug and performance tune the system 3 1 2 Software Versus Hardware Instrumentation Software monitoring consists of instrumentation code that is part of the target application This code is executed at run time and data about the events of interest i...

Page 65: ...s in real time while the target is running The subsections that follow briefly introduce the RTA tools In order to use RTA tools your application must be configured to include support for RTA You may open RTA tools in CCStudio at any time typically just before running the target application or while the application is running To open the tool choose Tools RTA from the CCStudio menu bar This shows ...

Page 66: ...STS logging disables updates to the Statistics Data tool You can enable and disable various types of logging and diagnostics at run time To change the setting for a field click in the field so you can see the drop down arrow Click the drop down arrow and select Enable Logging or Disable Logging or for the Diagnostics row select RUNTIME_ON or RUNTIME_OFF Then click on or tab to another field to app...

Page 67: ...bar icons Toggle view with group setting on and off Shift G Open the Find In dialog for searching this log Open the Set Filter Expression dialog for filtering the log records to match a pattern Pause data updates from the target This is useful when you are using the Find or Filter dialogs Shift F5 Automatically fit the columns to their current contents Refresh data from the target This is useful i...

Page 68: ...t Selected This command lets you select a csv comma separated value file to contain the selected data Data Export All This command lets you select a csv comma separated value file to contain all the data currently displayed in the log Groups This command lets you define groups to contain various types of log messages 3 2 3 Printf Logs The Printf Log is a convenient way to view all the user generat...

Page 69: ... Axis or Both When you click on the graph a marker of the type you have selected is placed When you drag your mouse around the graph the time is shown in red Toggle view with group setting on and off Shift G If you have enabled the view with group setting you can choose to align a group by centering If you have enabled the view with group setting you can choose to align a group using a horizontal ...

Page 70: ...want to see Display As Choose the marker you want to use to display the data The default is a connected line but you can choose from various marker styles and sizes Auto Scale Scales the load data to fit the range in use For example if the range is between 70 and 90 it zooms in on that range to make changes more visible When auto scale is turned on the scale may change as new data arrives Reset Au...

Page 71: ...is tool are the raw data used to plot the CPU Load graph The toolbar icons and right click menu for the Load Data tool are the same as for the Raw Logs tool Section 3 2 2 3 2 6 Statistics Data The Statistics Data tool lets you view statistics about thread execution You can open this tool by choosing Tools RTA Statistics Data from the CCStudio menu bar By default the Statistics Data tool displays t...

Page 72: ...nt to debug before opening ROV 2 Choose Tools ROV from the CCSv4 menus This opens the ROV area at the bottom of the CCS window You can open ROV at any time while you have an application loaded 3 Run the application to a breakpoint at which you want to view information 4 In the left pane of the ROV select a module from the expandable tree 5 In the right pane of the ROV you may need to expand a hier...

Page 73: ...of 32 If the value on the target is 33 the module can report this as a problem Memory ROV may report bad memory accesses or other detectable problems ROV errors ROV reports standard exceptions if a corrupted data from the target causes ROV related code in a module to behave incorrectly 3 3 1 Tasks The properties listed for tasks TSK are as follows Name The name of the task The name is taken from t...

Page 74: ...e target State The software interrupt s current state Valid states are Inactive Ready and Running Priority The software interrupt s priority as set in the configuration or during creation Valid priorities are 0 through 15 Mailbox Value The software interrupt s current mailbox value Function The name of the function called by this software interrupt arg0 arg1 The arguments sent to the function by t...

Page 75: ...and choose the Go To command to display that MEM segment in the ROV tool 3 3 4 Semaphores The properties listed for semaphores SEM are as follows Name The name of the semaphore The name is taken from the label for statically configured semaphores and is generated for dynamically created semaphores The label matches the name in the configuration Handle The address of the semaphore object header on ...

Page 76: ...location of the heap Mem Segment The number of the memory segment in which the heap is located 3 3 6 Buffer Pools The properties listed for buffer pools BUF are as follows Name The name of the buffer pool object The name is taken from the label for statically configured pools and is generated for dynamically created pools The label matches the name in the configuration Segment ID The name of the m...

Page 77: ... for an STS object and the CPU load are computed on the host Computations needed for RTA tool displays are performed on the host LOG STS and TRC module operations are very fast and execute in constant time as shown in the following list LOG_printf and LOG_event approximately 25 instructions STS_add approximately 10 instructions STS_delta approximately 15 instructions TRC_enable and TRC_disable app...

Page 78: ... kernel These figures provide a general idea of the amount of code increase that can be expected when working with the instrumented kernel Table 3 1 uses as samples two projects that utilize many of the DSP BIOS features By including DSP BIOS modules the applications incorporate the instrumentation code Therefore the following numbers are representative of the amount of code size incurred by the i...

Page 79: ...rumentation 3 17 b Example Echo Description all sizes in MADUs C55x Platform C6000 Platform Size with non instrumented kernel 41 200 68 800 Size with instrumented kernel 42 800 76 200 Size increase with instrumented kernel 1 600 7 400 ...

Page 80: ...uencies or a statistical summary of data values that vary rapidly The rate at which these events occur or values change may be so high that it is either not possible to transfer the entire sequence to the host due to bandwidth limitations or the overhead of transferring this sequence to the host would interfere with program operation DSP BIOS provides the TRC Trace Manager module for controlling t...

Page 81: ...s RTA tool To access this tool choose Tools RTA Printf Logs from the CCStudio menu bar A log can be either fixed or circular This distinction is important in applications that enable and disable logging programmatically using the TRC module operations as described in section 3 4 4 Trace Manager TRC Module page 3 13 Fixed The log stores the first messages it receives and stops accepting messages wh...

Page 82: ...g to worry about synchronization Log messages shown in a message log window are numbered to indicate the order in which the events occurred These numbers are an increasing sequence starting at 0 If your log never fills up you can use a smaller log size If a circular log is not long enough or you do not poll the log often enough you may miss some log entries that are overwritten before they are pol...

Page 83: ...he count and total the Statistics Data tool calculates the average on the host Calling the STS_add operation updates the statistics object of the data series being studied For example you might study the pitch and gain in a software interrupt analysis algorithm or the expected and actual error in a closed loop control algorithm DSP BIOS statistics objects are also useful for tracking absolute CPU ...

Page 84: ... window and choosing Clear from the shortcut menu The host read and clear operations are performed with interrupts disabled to allow any thread to update any STS object reliably For example an HWI function can call STS_add on an STS object and no data is missing from any STS fields This instrumentation process provides minimal intrusion into the target program A call to STS_add requires approximat...

Page 85: ...ata An STS object can store summary information about the time series Ti The following code fragment illustrates the use of CLK_gethtime high resolution time STS_set and STS_delta to track statistical information about the time required to perform an algorithm STS_set stsObj CLK_gethtime do algorithm STS_delta stsObj CLK_gethtime STS_set saves the value of CLK_gethtime as the contents of the previ...

Page 86: ... for gathering information about differences between specific values Figure 3 3 shows current values when measuring differences from the base value Example 3 1 Gathering Information About Differences in Values Figure 3 3 Current Value Deltas From One STS_set STS_set sts targetValue T0 processing STS_delta sts currentValue T1 processing STS_delta sts currentValue T2 processing STS_delta sts current...

Page 87: ...alue The DSP BIOS online help describes statistics objects and their parameters See STS Module in the TMS320 DSP BIOS API Reference Guide for your platform for information on the STS module API calls STS_set sts baseValue processing STS_delta sts currentValue STS_set sts baseValue processing STS_delta sts currentValue STS_set sts baseValue processing STS_delta sts currentValue STS_set sts baseValu...

Page 88: ...r you enable the log By disabling tracing when an event occurs you can use a circular log to store the last n events before you disable the log 3 5 4 1 Control of Explicit Instrumentation You can use the TRC module to control explicit instrumentation as shown in this code fragment if TRC_query TRC_USER0 0 LOG or STS operation Note TRC_query returns 0 if all trace types in the mask passed to it are...

Page 89: ...TRC_LOGTSK Logs events when a task is made ready starts becomes blocked resumes execution and terminates This constant also logs semaphore posts on TRC_STSHWI Gathers statistics on monitored register values within HWIs on TRC_STSPIP Counts the number of frames read from or written to data pipe on TRC_STSPRD Gathers statistics on the number of ticks elapsed during execution of periodic functions on...

Page 90: ...the balance between information gathering and time intrusion at run time By disabling various implicit instrumentation types you lose information but reduce the over head of processing From the target code enable and disable trace bits using the TRC_enable and TRC_disable operations respectively For example the following C code disables tracing of log information for software interrupts and period...

Page 91: ... of instruction cycles that the CPU spends doing application work That is the percentage of the total time that the CPU is Running hardware interrupts software interrupts tasks or periodic functions Performing I O with the host Running any user routine In power save or hardware idle mode C55x only When the CPU is not doing any of these it is considered idle Although the CPU is idle during power sa...

Page 92: ...DL objects In other words the CPU idle time in a DSP BIOS application is the time that the CPU spends doing the routine in Example 3 3 To measure the CPU load in a DSP BIOS application over a time interval T it is sufficient to know how much time was spent going through the loop shown in Figure 3 3 and how much time was spent doing application work Example 3 3 The Idle Loop Over a period of time T...

Page 93: ...d the System Clock page 4 71 This information is used by the host to calculate the CPU load according to the equation above The host uploads the STS objects from the target at the polling rate set in the RTA Control Panel Property Page The information contained in IDL_busyObj is used to calculate the CPU load The IDL_busyObj count provides a measure of N the number of times the idle loop ran The I...

Page 94: ... function reads the selected data location passes the value to the selected STS operation and finally branches to the HWI function The enable HWI accumulations check box in the RTA Control Panel must be selected in order for HWI function monitoring to take place If this type of tracing is not enabled the stub function branches to the HWI function without updating the STS object The number of times...

Page 95: ...r program and use the nmti program which is described in Chapter 2 Utility Programs in the TMS320 DSP BIOS API Reference Guide for your platform to find the address of the end of the system stack Or you can find the address in Code Composer by using a Memory window or the map file to find the address referenced by the GBL_stackend symbol This symbol references the top of the stack 3 Run your progr...

Page 96: ...or any HWI object Such monitoring is not enabled by default The performance of your interrupt processing is not affected unless you enable this type of instrumentation in the configuration The statistics object is updated each time hardware interrupt processing begins Updating such a statistics object consumes between 20 and 30 instructions per interrupt for each interrupt monitored Configured Sta...

Page 97: ... select For all these operations the number of times this hardware interrupt has been executed is stored in the count field see Figure 3 2 The max and total values are stored in the STS object on the target The average is computed on the host C55x Platform C6000 Platform C28x Platform Data Value Data Value Data Value Top of system stack Stack pointer Stack Pointer Stack Pointer General purpose reg...

Page 98: ...on STS Operation Result STS_add addr Stores maximum and total for the data value or register value STS_delta addr Compares the data value or register value to the prev property of the STS object or a value set consistently with STS_set and stores the maximum and total differences STS_add addr Negates the data value or register value and stores the maximum and total As a result the value stored as ...

Page 99: ...tor a Data Value 2 Set the addr parameter to the address of the timer counter register for the on device timer used by the CLK Manager 3 Set the type to unsigned 4 Set the operation parameter to STS_add addr 5 Set the Host Operation parameter of the corresponding STS object HWI_INT14_STS to A X B Set A to 4 and B to 0 1 Configure the HWI_TINT object to monitor the tim register 2 Set the operation ...

Page 100: ...sentation of the way your system actually operates Note RTDX is occasionally not supported for the initial releases of a new DSP device or board RTDX consists of both target and host components A small RTDX software library runs on the target DSP The DSP application makes function calls to this library s API in order to pass data to or from it This library makes use of a scan based emulator to mov...

Page 101: ...n is running For all of these applications you can select visualization tools that display information in a way that is most meaningful to you 3 8 2 RTDX Usage RTDX can be used with or without DSP BIOS RTDX is available with the PC hosted Code Composer Studio running Windows 98 or Windows NT version 4 0 RTDX in simulation is supported This document assumes that the reader is familiar with C Visual...

Page 102: ... Flow For the target to receive data from the host you must first declare an input channel and request data from it using routines defined in the user interface The request for data is recorded into the RTDX target buffer and sent to the host via the JTAG interface An OLE automation client can send data to the target using the OLE Interface All data to be sent to the target is written to a memory ...

Page 103: ... buffered by the RTDX Host Library Enable an OLE automation client to send data to the target via the RTDX host library 3 8 4 RTDX Modes The RTDX host library provides the following modes of receiving data from a target application Non continuous The data is written to a log file on the host Noncontinuous mode should be used when you want to capture a finite amount of data and record it in a log f...

Page 104: ...ed to increase the size of the buffer if you are transferring blocks of data larger than the default buffer size You can change the RTDX buffer size in the tcf configuration file 3 8 7 Sending Data From Target to Host or Host to Target The user library interface provides the data types and functions for Sending data from the target to the host Sending data from the host to the target The following...

Page 105: ...uring program execution 4 1 Overview of Thread Scheduling 4 2 4 2 Hardware Interrupts 4 11 4 3 Software Interrupts 4 25 4 4 Tasks 4 39 4 5 The Idle Loop 4 49 4 6 Power Management 4 51 4 7 Semaphores 4 59 4 8 Mailboxes 4 65 4 9 Timers Interrupts and the System Clock 4 71 4 10 Periodic Function Manager PRD and the System Clock 4 76 Topic Page ...

Page 106: ... centralized polling loop for example are easier to design implement and maintain DSP BIOS provides support for several types of program threads with different priorities Each thread type has different execution and preemption characteristics The thread types from highest to lowest priority are Hardware interrupts HWI which includes CLK functions Software interrupts SWI which includes PRD function...

Page 107: ... for inter task communication and synchronization These structures include queues semaphores and mailboxes See Section 4 4 Tasks page 4 39 for details about tasks Background thread Executes the idle loop IDL at the lowest priority in a DSP BIOS application After main returns a DSP BIOS application calls the startup routine for each DSP BIOS module and then falls into the idle loop The idle loop is...

Page 108: ...ority processing Using lower priority threads minimizes the length of time interrupts are disabled interrupt latency allowing other hardware interrupts to occur SWI versus TSK Use software interrupts if functions have relatively simple interdependencies and data sharing requirements Use tasks if the requirements are more complex While higher priority threads can preempt lower priority threads only...

Page 109: ...ristics Notes 1 If you disable the TSK Manager IDL threads use the system stack Characteristic HWI SWI TSK IDL Priority Highest 2nd highest 2nd lowest Lowest Number of priority levels DSP dependent 15 Periodic func tions run at priority of the PRD_swi SWI object Task sched uler runs at lowest priority 16 Including 1 for the ID loop 1 Can yield and pend No runs to completion except for preemption N...

Page 110: ...stack see Note 2 Entire context saved to task stack Not applicable Context saved when blocked Not applicable Not applicable Saves the C regis ter set see opti mizing compiler user s guide for your platform Not applicable Share data with thread via Streams queues pipes global variables Streams queues pipes global variables Streams queues pipes locks mailboxes global variables Streams queues pipes g...

Page 111: ...re interrupts have lower priority than hardware interrupts There are 14 priority levels available for software interrupts Software interrupts can be preempted by a higher priority software interrupt or any hardware interrupt Software interrupts cannot block Tasks have lower priority than software interrupts There are 15 task priority levels Tasks can be preempted by any higher priority thread Task...

Page 112: ...M_pend Both hardware and software interrupts can interact with the DSP BIOS task scheduler When a task is blocked it is often because the task is pending on a semaphore which is unavailable Semaphores can be posted from HWIs and SWIs as well as from other tasks If an HWI or SWI posts a semaphore to unblock a pending task the processor switches to that task if that task has a higher priority than t...

Page 113: ...The second ISR is held off because the first ISR masks off that is disables the second interrupt during the first ISR Thread Running Thread Posted HWI SWI TSK IDL Enabled HWI Preempts Preempts Preempts Preempts Disabled HWI Waits for reenable Waits for reenable Waits for reenable Waits for reenable Enabled higher priority SWI Preempts Preempts Preempts Disabled SWI Waits Waits for reenable Waits f...

Page 114: ...mption Scenario In Figure 4 2 the low priority software interrupt is asynchronously preempted by the hardware interrupts The first ISR posts a higher priority software interrupt which is executed after both hardware interrupt routines finish executing ...

Page 115: ...one time For this reason you should minimize the amount of code performed by an HWI function If the GIE bit is enabled a hardware interrupt can be preempted by any interrupt that is enabled by the IEMASK If an HWI function calls any of the PIP APIs PIP_alloc PIP_free PIP_get PIP_put the pipe s notifyWriter or notifyReader functions run as part of the HWI context Note The interrupt keyword or INTER...

Page 116: ...its in the interrupt enable register To reenable interrupts call HWI_enable or HWI_restore HWI_enable always enables the GIE bit on the C6000 platform or clears the INTM bit in the ST1 register on the C5000 and C2800 platforms while HWI_restore restores the value to the state that existed before HWI_disable was called 4 2 3 Impact of Real Time Mode Emulation on DSP BIOS TI Emulation supports two d...

Page 117: ...de This is identical to the behavior of breakpoints when in stopmode Note that software breakpoints replace the original instruction so it is not possible to safely ignore or delay the software breakpoint s execution otherwise you will not be executing the intended set of instructions However other forms of causes of halting the CPU can be delayed It s important to note that placing software break...

Page 118: ...ACC Do some more stuff IRET Note The code above is safe if the debugger issues a halt you cannot halt in the italicized regions above so the PC will always be at the B MAIN_LOOP instruction If the user sets a watchpoint to occur when the address Semaphore is accessed the CPU will not be able to halt until after CLRC INTM DBGM is executed The same result will occur if the user sets a hardware break...

Page 119: ... to CPU Check DBGIER bit Check IER bit Clear corresponding IER bit Empty pipeline Increment and temporarily store PC Fetch interrupt vector Increment SP by 1 Perform automatic context save Clear corresponding IER bit Set INTM DBGM Clear loop EALLOW IDLESTAT Load PC with fetch vector Execute interrupt service routine Program continues ...

Page 120: ...ever if STEP 1 was used to enter the state CPU cannot service the interrupt This is true for both stop mode and real time mode Note that it is safe to assume that INTM will be respected while single stepping Also if you single step the code from the previous example all of the uninterruptible unhaltable code will be executed as one instruction as follows PC initially here SETC INTM DBGM Uninterrup...

Page 121: ...re 4 4 The Interrupt Sequence in the Run time State No No Yes Yes Interrupt request sent to CPU Check INTM bit Check IER bit Clear corresponding IER bit Empty pipeline Increment and temporarily store PC Fetch interrupt vector Increment SP by 1 Perform automatic context save Clear corresponding IER bit Set INTM DBGM Clear loop EALLOW IDLESTAT Load PC with fetch vector Execute interrupt service rout...

Page 122: ... call to HWI_disable turns interrupts off and the innermost call to HWI_disable does nothing Interrupts are not reenabled until the outermost call to HWI_restore Be careful when using HWI_enable because this call enables interrupts even if they were already disabled when HWI_disable was called Note DSP BIOS kernel calls that can cause task rescheduling for example SEM_post and TSK_sleep should be ...

Page 123: ...e function s code In order to support interrupt routines written completely in C DSP BIOS provides an HWI dispatcher that performs these enter and exit macros for an interrupt routine An HWI can handle context saving and interrupt disabling using this HWI dispatcher or by explicitly calling HWI_enter and HWI_exit The HWI configuration properties allow you to choose whether the HWI dispatcher is us...

Page 124: ... HWI_enter and HWI_exit both take four parameters on the C6000 platform The first two ABMASK and CMASK specify which A B and control registers are to be saved and restored by the ISR The third parameter on the C6000 platform IEMASK is a mask of those interrupts that are to be disabled between the HWI_enter and HWI_exit macro calls When an interrupt is triggered the processor disables interrupts gl...

Page 125: ...gisters that can be freely used by a C function When using the HWI dispatcher on the C6000 platform there is no ability to specify a register set so the registers specified by these masks are all saved and restored For example if your HWI function calls a C function you would use HWI_enter C62_ABTEMPS C62_CTEMPS IEMASK CCMASK isr code HWI_exit C62_ABTEMPS C62_CTEMPS IEMASK CCMASK HWI_enter should ...

Page 126: ...he current HWI function When HWI_exit is called you can also provide the IERRESTOREMASK parameter The bit pattern in the IERRESTOREMASK determines what interrupts are restored by HWI_exit by setting the corresponding bits in the IER Of the interrupts in IERRESTOREMASK HWI_exit restores only those that were disabled with HWI_enter If upon exiting the ISR you do not wish to restore one of the interr...

Page 127: ... itick C function mvkl tiret b3 mvkh tiret b3 nop 3 tiret restore saved registers and call DSP BIOS scheduler HWI_exit C62_ABTEMPS C62_CTEMPS IEMASK CCMASK end _DSS_isr _DSS_isr HWI_enter C55_AR_T_SAVE_BY_CALLER_MASK C55_ACC_SAVE_BY_CALLER_MASK C55_MISC1_SAVE_BY_CALLER_MASK C55_MISC2_SAVE_BY_CALLER_MASK C55_MISC3_SAVE_BY_CALLER_MASK 0FFF7h 0 macro has ensured C convention including SP alignment ca...

Page 128: ...compiler code For more information either about which registers are saved and restored or by the TMS320 functions conforming to the Texas Instruments C run time model see the optimizing compiler user s guide for your platform _DSS_isr _DSS_isr HWI_enter AR_MASK ACC_MASK MISC_MASK IERDISABLEMASK lcr _DSS_cisr HWI_exit AR_MASK ACC_MASK MISC_MASK IERDISABLEMASK ...

Page 129: ...execution of all software interrupts When the application calls one of the APIs above the SWI Manager schedules the function corresponding to the software interrupt for execution To handle all software interrupts in an application the SWI Manager uses SWI objects If a software interrupt is posted it runs only after all pending hardware interrupts have run An SWI routine in progress can be preempte...

Page 130: ...ed for execution The DSP BIOS online help describes SWI objects and their properties See SWI Module in the TMS320 DSP BIOS API Reference Guide for your platform for reference information on the SWI module API calls To create a software interrupt dynamically use a call with this syntax swi SWI_create attrs Here swi is the interrupt handle and the variable attrs points to the SWI attributes The SWI ...

Page 131: ...deadline and a lower priority for a software interrupt that handles a thread with a less critical execution deadline To set software interrupt priorities with the Configuration Tool follow these steps 1 In the Configuration Tool highlight the Software Interrupt Manager Notice SWI objects in the middle pane of the window shown in Figure 4 5 They are organized in priority level folders If you do not...

Page 132: ... is the highest level You can also set the priority by selecting the priority level from the menu in the Property window as shown in Figure 4 6 Figure 4 6 SWI Properties Dialog Box 4 3 3 Software Interrupt Priorities and Application Stack Size All threads in DSP BIOS excluding tasks are executed using the same system stack The system stack stores the register context when a software interrupt pree...

Page 133: ...SWI_andn SWI_dec SWI_inc SWI_or and SWI_post These calls can be used virtually anywhere in the program interrupt service routines periodic functions idle functions or other software interrupt functions When an SWI object is posted the SWI Manager adds it to a list of posted software interrupts that are pending execution Then the SWI Manager checks whether software interrupts are currently enabled ...

Page 134: ...rupt flag bit in the interrupt flag register See Section 4 3 5 Using an SWI Object s Mailbox page 4 30 for more information on how to handle SWIs that are posted multiple times before they are scheduled for execution Applications should not make any assumptions about the order in which SWI handlers of equal priority are called However an SWI handler can safely post itself or be posted by another i...

Page 135: ...its initial value The initial value of the mailbox should be set in the tcf configuration file If while the SWI function is executing it is posted again its mailbox is updated accordingly However this does not affect the value returned by SWI_getmbox while the SWI functions execute That is the mailbox value that SWI_getmbox returns is the latched mailbox value when the software interrupt was remov...

Page 136: ...Post an SWI Program configuration SWI object myswi Function myswiFxn Program execution Calls SWI_inc myswi myswi is posted Calls SWI_inc myswi myswi is posted again before it is scheduled for execution SWI manager removes myswi from the posted SWI queue myswiFxn is scheduled for execution myswiFxn starts execution Mailbox value Value returned by SWI_getmbox 0 1 2 0 2 0 2 myswiFxn is preempted by I...

Page 137: ...cesses is ready Figure 4 8 Using SWI_andn to Post an SWI In some situations the SWI function can call different routines depending on the event that posted it In that case the program can use SWI_or to post the SWI object unconditionally when an event happens This is shown in Figure 4 9 The value of the bitmask used by SWI_or encodes the event type that triggered the post operation and can be used...

Page 138: ...ime the event occurs the SWI is posted only after its mailbox reaches 0 that is after the event has occurred a number of times equal to the mailbox value Program configuration SWI object myswi Function myswiFxn Program execution Calls SWI_or myswi 0x1 myswi is posted myswiFxn is executed Calls SWI_or myswi 0x2 myswi is posted myswiFxn is executed Mailbox value Value returned by SWI_getmbox 0 0 0 0...

Page 139: ...ta structure is modified by an SWI handler instead of an HWI mutual exclusion can be achieved by disabling software interrupts while the task accesses the shared data structure SWI_disable and SWI_enable are described later in this chapter Thus there is no effect on the ability of the system to respond to events in real time using hardware interrupts It often makes sense to break long ISRs into tw...

Page 140: ...M_pend or any function that calls SEM_pend for example MEM_alloc TSK_sleep On the other hand an SWI handler must complete before any blocked task is allowed to run There might be situations where the use of a task might fit better with the overall system design in spite of any additional overhead involved 4 3 7 Saving Registers During Software Interrupt Preemption When a software interrupt preempt...

Page 141: ...riggered 4 3 8 Synchronizing SWI Handlers Within an idle loop function task or software interrupt function you can temporarily prevent preemption by a higher priority software interrupt by calling SWI_disable which disables all SWI preemption To reenable SWI preemption call SWI_enable Software interrupts are enabled or disabled as a group An individual software interrupt cannot be enabled or disab...

Page 142: ...k preemption is also disabled This is because DSP BIOS uses software interrupts internally to manage semaphores and clock ticks To delete a dynamically created software interrupt use SWI_delete The memory associated with swi is freed SWI_delete can only be called from the task level ...

Page 143: ...r storing local variables as well as for further nesting of function calls Stack size can be specified separately for each TSK object Each stack must be large enough to handle normal subroutine calls as well as a single task preemption context A task preemption context is the context that gets saved when one task preempts another as a result of an interrupt thread readying a higher priority task I...

Page 144: ...resources is often an application design error although not necessarily so In most cases such resources should be released prior to deleting the task Void TSK_delete task TSK_Handle task Note Catastrophic failure can occur if you delete a task that owns resources that are needed by other tasks in the system See TSK_delete in the TMS320 DSP BIOS API Reference Guide for your platform for details 4 4...

Page 145: ...e of four possible states of execution 1 Running which means the task is the one actually executing on the system s processor 2 Ready which means the task is scheduled for execution subject to processor availability 3 Blocked which means the task cannot execute until a particular event occurs within the system or 4 Terminated which means the task is terminated and does not execute again Tasks are ...

Page 146: ...SK_idle task whose priority is lower than all other tasks in the system When a task is preempted by a software or hardware interrupt the task execution mode returned for that task by TSK_stat is still TSK_RUNNING because the task will run when the preemption ends Note Do not make blocking calls such as SEM_pend or TSK_sleep from within an IDL function Doing so prevents DSP BIOS Analysis Tools from...

Page 147: ...ability of a shared resource the elapse of a specified period of time and so forth By virtue of becoming TSK_READY this task is scheduled for execution according to its priority level and of course this task immediately transitions to the running state if its priority is higher than the currently executing task TSK schedules tasks of equal priority on a first come first served basis 4 4 3 Testing ...

Page 148: ...odule hook functions you have specified are automatically placed in a HOOK object called HOOK_KNL To set any properties of this object other than the Initialization function use the TSK module properties To set the Initialization function property of the HOOK_KNL object use the HOOK object properties If you configure only a single set of hook functions using the TSK module the HOOK module is not u...

Page 149: ...tenv task context set task environment Void doDelete task TSK_Handle task Ptr context context TSK_getenv task get register buffer MEM_free 0 context CONTEXTSIZE Void doSwitch from to TSK_Handle from TSK_Handle to Ptr context static Int first TRUE if first first FALSE return context TSK_getenv from get register buffer context hardware registers save registers context TSK_getenv to get register buff...

Page 150: ...e slice scheduling among three tasks of equal priority A fourth task of higher priority periodically preempts execution A PRD object drives the time slice scheduling Every millisecond the PRD object calls TSK_yield which forces the current task to relinquish access to to the CPU The time slicing could also be driven by a CLK object as long as the time slice was the same interval as the clock inter...

Page 151: ... work load of the time sharing tasks while 1 time CLK_gethtime counts_per_us print time only every 200 usec if time prevtime 200 prevtime time LOG_printf trace Task d time is us Ox x id Int time check for rollover if prevtime time prevtime time pass through idle loop to pump data to the Real Time Analysis tools TSK_disable IDL_run TSK_enable hi_pri_task Void hi_pri_task Arg id_arg Int id ArgToInt ...

Page 152: ...Tasks 4 48 Figure 4 12 Trace from Example 4 7 ...

Page 153: ...loop functions run only when no other hardware interrupts software interrupts or tasks need to run Communication between the target and the DSP BIOS Analysis Tools is performed within the background idle loop This ensures that the DSP BIOS Analysis Tools do not interfere with the program s processing If the target CPU is too busy to perform background processes the DSP BIOS Analysis Tools stop rec...

Page 154: ...to the host via LNK_dataPump IDL_cpuLoad uses an STS object IDL_busyObj to calculate the target load The contents of this object are uploaded to the DSP BIOS Analysis Tools through RTA_dispatcher to display the CPU load PWRM_idleDomains calls a function to idle various DSP clock domains within the DSP BIOS idle loop Various clock domains to idle can be selected in the PWRM module configuration Whe...

Page 155: ...they sit in their lowest power state until they are needed Resource Tracking You can make runtime PWRM API calls to inform the Power Manager of the specific resources for example clock domains peripherals and clock pins that your application is dependent upon With this knowledge of required resources PWRM can aggressively idle resources that have no declared dependencies Scaling Voltage and Freque...

Page 156: ... dynamically with the PWRM_configure function When PWRM is configured to idle clock domains in the IDL loop other IDL loop processing does not run as regularly as it did previously For example when real time analysis is enabled the idle loop runs functions to compute the CPU load to gather real time analysis data from the DSP and to pump data from the DSP to Code Composer Studio When PWRM idling i...

Page 157: ...ble as ON or OFF The PWRM actions during device initialization are device specific and are described in the corresponding DSP BIOS release notes 4 6 4 Resource Tracking A typical DSP BIOS application uses a set of peripherals timers serial ports etc to accomplish its purpose Typically device drivers manage low level peripheral accesses but sometimes applications access peripherals directly In both...

Page 158: ... dissipation of a CMOS based DSP is linearly proportional to the clock rate frequency and quadratically proportional to the operating voltage Additionally the operating voltage determines the maximum clock rate available Therefore if an application can reduce the CPU clock rate and still meet its processing deadlines it can produce a linearly proportional savings in power dissipation However reduc...

Page 159: ... To minimize disruption the PWRM module allows the DSP BIOS CLK module to register for notification of V F scaling events When notified of a new V F setpoint the CLK module reprograms the timer to tick at the same rate used prior to the scaling operation As a result low resolution time CLK_getltime continues to function following frequency scaling However a small amount of absolute time may be los...

Page 160: ... supports coordination of sleep state changes across the application through a registration and notification mechanism For example a driver that controls an external codec can register to be notified when the DSP is going to deep sleep so that it can tell the external device to go to a low power state When the DSP wakes from deep sleep the driver again gets notified and sends the appropriate comma...

Page 161: ...he application registers control code with the power manager PWRM so that it can change EMIF settings when there is a change to the setpoint 2 A DSP BIOS link driver using DMA for transfers to from external memory registers to be notified of V F setpoint changes For example prior to a setpoint change the driver may need to temporarily stop DMA operations to external memory 3 Packaged target conten...

Page 162: ...If a client does not signal that it is done within the timeout specified PWRM returns PWRM_ETIMEOUT indicating a system failure Before notifying clients of a power event PWRM firsts disable SWI and TSK scheduling to protect against preemption while the event is being processed The following table shows when SWI and TSK scheduling is disabled and re enabled around event processing Since SWI and TSK...

Page 163: ...ally See Section 2 4 Creating DSP BIOS Objects Dynamically page 2 16 for a discussion of the benefits of creating objects statically Example 4 8 Creating and Deleting a Semaphore The semaphore count is initialized to count when it is created In general count is set to the number of resources that the semaphore is synchronizing SEM_pend waits for a semaphore If the semaphore count is greater than 0...

Page 164: ...at another message has been enqueued The reader task calls SEM_pend to wait for messages SEM_pend returns only when a message is available on the queue The reader task prints the message using the LOG_printf function The three writer tasks reader task semaphore and queues in this example program were created statically Since this program employs multiple tasks a counting semaphore is used to synch...

Page 165: ... tasks SEM_pend and SEM_post are used to synchronize access to the message queue id field was added to MsgObj to specify writer task id Unlike a mailbox a queue can hold an arbitrary number of messages or elements Each message must however be a structure with a QUE_Elem as its first field include std h include log h include mem h include que h include sem h include sys h include tsk h include trc ...

Page 166: ...GS sizeof MsgObj 0 if msg MEM_ILLEGAL SYS_abort Memory allocation failed n Put all messages on freequeue for i 0 i NUMMSGS msg i QUE_put freeQueue msg reader Void reader Msg msg Int i for i 0 i NUMMSGS NUMWRITERS i Wait for semaphore to be posted by writer SEM_pend sem SYS_FOREVER dequeue message msg QUE_get msgQueue print value LOG_printf trace read c from d msg val msg id free msg QUE_put freeQu...

Page 167: ... Void writer Int id Msg msg Int i for i 0 i NUMMSGS i Get msg from the free queue Since reader is higher priority and only blocks on sem this queue is never empty if QUE_empty freeQueue SYS_abort Empty free queue n msg QUE_get freeQueue fill in value msg id id msg val i 0xf a LOG_printf trace d writing c id msg val enqueue message QUE_put msgQueue msg post semaphore SEM_post sem what happens if yo...

Page 168: ...Semaphores 4 64 Figure 4 14 Trace Results from Example 4 11 ...

Page 169: ...fits of creating objects statically You specify the mailbox length and message size when you create a mailbox as shown in Example 4 12 Example 4 12 Creating a Mailbox MBX_pend is used to read a message from a mailbox as shown in Example 4 13 If no message is available that is the mailbox is empty MBX_pend blocks In this case the timeout parameter allows the task to wait until a timeout to wait ind...

Page 170: ...messages into the mailbox The resultant trace from Example 4 15 is shown in Figure 4 15 Note When called within an HWI the code sequence calling MBX_post must be either wrapped within an HWI_enter HWI_exit pair or invoked by the HWI dispatcher Bool MBX_post mbx msg timeout MBX_Handle mbx Void msg Uns timeout return after this many system clock ticks Bool MBX_post mbx msg timeout MBX_Handle mbx Voi...

Page 171: ...place of QUE and SEM the elem field is removed from MsgObj reader task is not higher priority than writer task reader looks at return value of MBX_pend for timeout include std h include log h include mbx h include tsk h define NUMMSGS 3 number of messages define TIMEOUT 10 typedef struct MsgObj Int id writer task id Char val message value MsgObj Msg Mailbox created with Config Tool extern MBX_Obj ...

Page 172: ...sted by writer if MBX_pend mbx msg TIMEOUT 0 LOG_printf trace timeout expired for MBX_pend break print value LOG_printf trace read c from d msg val msg id LOG_printf trace reader done writer Void writer Int id MsgObj msg Int i for i 0 i NUMMSGS i fill in value msg id id msg val i NUMMSGS Int a LOG_printf trace d writing c id Int msg val enqueue message MBX_post mbx msg TIMEOUT what happens if you ...

Page 173: ...mailbox this counting semaphore is initially set to zero so that reader tasks block on empty mailboxes When messages are posted to the mailbox this semaphore is incremented In Example 4 15 all the tasks have the same priority The writer tasks try to post all their messages but a full mailbox causes each writer to block indefinitely The readers then read the messages until they block on an empty ma...

Page 174: ...s of scheduling order and priority the number of participants the mailbox length and the wait time by combining the following code modifications Creation order or priority of tasks Number of readers and writers Mailbox length parameter MBXLENGTH Add code to handle a writer task timeout ...

Page 175: ...perties of the CLK ISR DSP BIOS provides two separate timing methods the high and low resolution times and the system clock In the default configuration the low resolution time and the system clock are the same However your program can drive the system clock using some other event such as the availability of data You can disable or enable the CLK Manager s use of the on device timer to drive high ...

Page 176: ...nce Guide for your platform and TDDR is the value of the timer divide down register as shown in the following equation When this register reaches 0 on the C28x platform or the value set for the period register on the C6000 platform the counter is reset On the C28x it is reset to the value in the period register On the C6000 it is reset to 0 At this point a timer interrupt occurs When a timer inter...

Page 177: ... maximum 32 bit value is reached On the C28x platform the 32 bit high resolution time is calculated by multiplying the low resolution time that is interrupt count by the value of the period register and adding the difference between the period register value and the value of the timer counter register To obtain the value of the high resolution time you can call CLK_gethtime from your application c...

Page 178: ... TSK_sleep 1000 Note Do not call TSK_sleep or SEM_pend with a timeout other than 0 or SYS_FOREVER if the program is configured without something to drive the PRD module In a default configuration the CLK module drives the PRD module If you are using the default CLK configuration the system clock has the same value as the low resolution time because the PRD_clock CLK object drives the system clock ...

Page 179: ... 16 would be similar to that shown in Example 4 17 Example 4 16 Using the System Clock to Drive a Task Note Non pointer type function arguments to LOG_printf need explicit type casting to Arg as shown in the following code example LOG_printf trace Task d Done Arg id clktest c In this example a task goes to sleep for 1 sec and prints the time after it wakes up include std h include log h include cl...

Page 180: ...PRD object is specified in terms of the system clock time that is in system clock ticks To schedule functions based on certain events use the following procedures Based on a real time clock Set the Use CLK Manager to Drive PRD property to true for the PRD module properties By doing this you are setting the timer interrupt used by the CLK Manager to drive the system clock When you do this a CLK obj...

Page 181: ... the time the system tick occurs and the execution of the periodic objects whose periods have expired with the tick If these functions run immediately after the tick you should configure PRD_swi to have a high priority with respect to other threads in your application 4 10 2 Interpreting PRD and SWI Statistics Many tasks in a real time system are periodic that is they execute continuously and at r...

Page 182: ...vide an immediate indication when these situations exist When statistics accumulators for software interrupts and periodic objects are enabled the host automatically gathers the count total maximum and average for the following types of statistics SWI Statistics about the period elapsed from the time the software interrupt was posted to its completion PRD The number of periodic system ticks elapse...

Page 183: ... BUF which manage allocation of variable length and fixed length memory SYS which provides miscellaneous system services QUE which manages queues This chapter also presents several simple example programs that use these modules The API functions are described in greater detail in the TMS320 DSP BIOS API Reference Guide for your platform 5 1 Memory Management 5 2 5 2 System Services 5 12 5 3 Queues...

Page 184: ...Such configuration is your responsibility and is typically handled by software loading programs or in the case of Code Composer Studio the GEL start up or menu options For example to access external memory on a C6000 platform the External Memory Interface EMIF registers must first be set appropriately before any access The earliest opportunity for EMIF initialization within DSP BIOS would be durin...

Page 185: ...s for other objects 5 1 2 Disabling Dynamic Memory Allocation If small code size is important to your application you can reduce code size significantly by removing the capability to dynamically allocate and free memory If you remove this capability your program cannot call any of the MEM functions or any object creation functions such as TSK_create You should create all objects that are used by y...

Page 186: ...l designcfg cmd SECTIONS place high performance code in on device ram fast_text myfastcode lib text myfastcode lib switch IPRAM all other user code in off device ram text SDRAM0 switch SDRAM0 cinit SDRAM0 pinit SDRAM0 user data in on device ram bss IDRAM far IDRAM First include DSP BIOS generated cmd file l designcfg cmd SECTIONS place high performance code in on device ram fast_text myfastcode li...

Page 187: ...me defined in the configuration The memory block returned by MEM_alloc contains at least the number of minimum addressable data units MADUs indicated by the size parameter A minimum addressable unit for a processor is the smallest datum that can be loaded or stored in memory An MADU can be viewed as the number of bits between consecutive memory addresses The number of bits in an MADU varies with d...

Page 188: ...g the block of storage Example 5 5 Using MEM_free to Free Memory Example 5 6 displays a function call which frees the array of objects allocated in Example 5 5 Example 5 6 Freeing an Array of Objects 5 1 4 2 Memory Allocation with the BUF Module The BUF module maintains pools of fixed size buffers These buffer pools can be created statically or dynamically Dynamically created buffer pools are allo...

Page 189: ...mory Segment You can use MEM_stat to obtain the status of a memory segment in the number of minimum addressable data units MADUs In a manner similar to MEM_alloc MEM_calloc and MEM_valloc refer to Example 5 3 the size used and length values are returned by MEM_stat If you are using the BUF module you can call BUF_stat to get statistics for a buffer pool You can also call BUF_maxbuff to get the max...

Page 190: ...d MEM_free to highlight several issues involved with memory allocation Figure 5 2 shows the trace results from Example 5 7 or Example 5 8 In Example 5 7 and Example 5 8 memory is allocated from IDATA and IDRAM memory using MEM_alloc and later freed using MEM_free printmem is used to print the memory status to the trace buffer The final values for example after freeing should match the initial valu...

Page 191: ...extern Int IDATA endif ifdef 55 extern Int DATA endif static Void printmem Int segid main Void main Int i Ptr ram NALLOCS LOG_printf trace before allocating print initial memory status printmem IDATA LOG_printf trace allocating allocate some memory from each segment for i 0 i NALLOCS i ram i MEM_alloc IDATA BUFSIZE 0 LOG_printf trace seg d ptr 0x x IDATA ram i LOG_printf trace after allocating pri...

Page 192: ...LOG_printf trace before allocating print initial memory status printmem IDRAM LOG_printf trace allocating allocate some memory from each segment for i 0 i NALLOCS i ram i MEM_alloc IDRAM BUFSIZE 0 LOG_printf trace seg d ptr 0x x IDRAM ram i LOG_printf trace after allocating print memory status printmem IDRAM free memory for i 0 i NALLOCS i MEM_free IDRAM ram i BUFSIZE LOG_printf trace after freein...

Page 193: ...The program in Example 5 7 and Example 5 8 gives board dependent results O indicates the original amount of memory U the amount of memory used and A the length in MADUs of the largest contiguous free block of memory The addresses you see are likely to differ from those shown in Example 5 2 ...

Page 194: ...exiting or aborting programs are inherently system dependent you can modify configuration settings to invoke your own routines whenever SYS_exit or SYS_abort is called Example 5 9 Coding To Halt Program Execution with SYS_exit or SYS_abort The functions in Example 5 9 terminate execution by calling whatever routine is specified for the Exit function and Abort function properties of the SYS module ...

Page 195: ...kewise calls whatever function is bound to the Exit function property passing on its original status parameter SYS_exit first executes a set of handlers registered through the function SYS_atexit as described Example 5 11 Example 5 11 Using Handlers in SYS_exit The function SYS_atexit provides a mechanism that enables you to stack up to SYS_NUMHANDLERS which is set to 8 clean up routines as shown ...

Page 196: ... number and associated error string Example 5 14 Using doError to Print Error Information The errno parameter to SYS_error can be a DSP BIOS error for example SYS_EALLOC or a user error errno 256 See TMS320 DSP BIOS API Reference Guide for your platform for a table of error codes and strings Note Error checking that would increase memory and CPU requirements has been kept to a minimum in the DSP B...

Page 197: ...ing Queues 5 3 1 Atomic QUE Functions QUE_put and QUE_get are used to atomically insert an element at the tail of the queue or remove an element from the head of the queue These functions are atomic in that elements are inserted and removed with interrupts disabled Therefore multiple threads can safely use these two functions to modify a queue without any external synchronization QUE_get atomicall...

Page 198: ... a pointer to the next element in the queue and QUE_prev returns a pointer to the previous element in the queue QUE_insert and QUE_remove are used to insert or remove an element from an arbitrary point within the queue Example 5 17 Using QUE Functions with Mutual Exclusion Elements Note Since QUE queues are implemented as doubly linked lists with a header node QUE_head QUE_next or QUE_prev may ret...

Page 199: ...use MEM_alloc and MEM_free to manage the MsgObj structures It would be way more efficient to preallocate a pool of MsgObj s and keep them on a free queue Using the Config Tool create freeQueue Then in main allocate the MsgObj s with MEM_alloc and add them to freeQueue with QUE_put You can then replace MEM_alloc calls with QUE_get freeQueue and MEM_free with QUE_put freeQueue msg A queue can hold a...

Page 200: ...e queue should never be empty if QUE_empty queue SYS_abort queue error n dequeue message msg QUE_get queue print value LOG_printf trace read c msg val free msg MEM_free 0 msg sizeof MsgObj writer Void writer Msg msg Int i for i 0 i NUMMSGS i allocate msg msg MEM_alloc 0 sizeof MsgObj 0 if msg MEM_ILLEGAL SYS_abort Memory allocation failed n fill in value msg val i a LOG_printf trace writing c msg ...

Page 201: ...vel Functions 5 19 Note Non pointer type function arguments to log_printf need explicit type casting to Arg as shown in the following code example LOG_printf trace Task d Done Arg id Figure 5 3 Trace Results from Example 5 18 ...

Page 202: ...5 20 ...

Page 203: ...a transfer methods and discusses pipes in particular 6 1 I O Overview 6 2 6 2 Comparing Pipes and Streams 6 3 6 3 Comparing Driver Models 6 5 6 4 Data Pipe Manager PIP Module 6 8 6 5 Message Queues 6 15 6 6 Host Channel Manager HST Module 6 27 6 7 I O Performance Issues 6 28 Topic Page ...

Page 204: ...ly ignorant of the details of an individual device s operation Figure 6 1 Input Output Stream An important aspect of stream I O is its asynchronous nature Buffers of data are input or output concurrently with computation While an application is processing the current buffer a new input buffer is being filled and a previous one is being output This efficient management of I O buffers allows streams...

Page 205: ...nd receiving of variable length messages This module can be used for messaging between multiple processors See section 6 5 Message Queues for a description of message queues Host channel objects allow an application to stream data between the target and the host Host channels are statically configured for input or output Each host channel is internally implemented using a data pipe object 6 2 Comp...

Page 206: ...and is generally faster More flexible generally simpler to use Each pipe owns its own buffers Buffers can be transferred from one stream to another without copying In practice copying is usually necessary anyway because the data is processed Pipes must be created statically in the configuration Streams can be created either at run time or statically in the configuration Streams can be opened by na...

Page 207: ...I O interface The application indirectly invokes DEV functions implemented by the device driver managing the physical device attached to the stream using generic functions provided by the SIO module The SIO DEV model cannot be used with pipes See Chapter 7 for more information on the SIO DEV model For either model you create a user defined device object using the DEV module The model used by this ...

Page 208: ... NULL device global data ptr status DEV_createDevice codec DSK6X_EDMA_IOMFXNS Fxn DSK6X_IOM_init gioAttrs 6 3 2 Creating a Device for Use with Streams and the DIO Adapter If you plan to use an IOM mini driver with SIO streams and the DIO adapter create a user defined device statically or with a DEV_createDevice call similar to that shown below DIO_Params dioCodecParams codec device name NULL chanP...

Page 209: ...V_SIOTYPE type of the device NULL device global data ptr status DEV_createDevice codec DSK6X_EDMA_DEVFXNS Fxn DSK6X_DEV_init devAttrs The device function tables passed to DEV_createDevice should be of type DEV_Fxns 6 3 4 Creating a Device for Use with Provided Software Drivers DSP BIOS provides several software drivers that use the SIO DEV model These are described in the DEV module section of the...

Page 210: ...med in the context of the function that calls PIP_free or PIP_put They can also be called from the thread that calls PIP_get or PIP_alloc When PIP_get is called DSP BIOS checks whether there are more full frames in the pipe If so the notifyReader function is executed When PIP_alloc is called DSP BIOS checks whether there are more empty frames in the pipe If so the notifyWriter function is executed...

Page 211: ...S checks whether there are additional empty frames available in the pipe If so the notifyWriter function is called at this time 4 Once PIP_alloc returns the empty frame can be used by the application code to store data To do this the function needs to know the frame s start address and its size The API function PIP_getWriterAddr returns the address of the beginning of the allocated frame The API f...

Page 212: ...e pipe If so the notifyReader function is called at this time 4 Once PIP_get returns the data in the full frame can be read by the application To do this the function needs to know the frame s start address and its size The API function PIP_getReaderAddr returns the address of the beginning of the full frame The API function PIP_getReaderSize returns the number of valid data words in the frame ext...

Page 213: ...ion 6 4 2 Reading Data from a Pipe page 6 10 demonstrate this type of polled read and write operation When used to buffer real time I O streams written read by a hardware peripheral pipe objects often serve as a data channel between the HWI routine triggered by the peripheral itself and the program function that ultimately reads writes the data In such situations the application can effectively sy...

Page 214: ...s a list of empty frames and a counter with the number of empty frames on the writer side of the pipe and a list of full frames and a counter with the number of full frames on the reader side of the pipe The pipe object also contains a descriptor of the current writer frame that is the last frame allocated and currently being filled by the application and the current reader frame that is the last ...

Page 215: ... so would overwrite previous descriptor information and produce undetermined results Example 6 4 Using PIP_get 6 4 4 1 Avoiding Recursion Problems Care should be applied when a pipe s notify function calls PIP APIs for the same pipe Consider the following example A pipe s notifyReader function calls PIP_get for the same pipe The pipe s reader is an HWI routine The pipe s writer is an SWI routine H...

Page 216: ...ads with different priorities call PIP_get for the same pipe This could have catastrophic consequences if one thread preempts the other and as a result PIP_get is called twice before calling PIP_free or PIP_get is preempted and called again for the same pipe from a different thread Note As a general rule to avoid recursion you should avoid calling PIP functions as part of notifyReader and notifyWr...

Page 217: ...ed when receiving messages Readers can determine the writer and reply back Receiving a message is deterministic when the timeout is zero Sending a message is deterministic the call but not the delivery Messages can reside on any message queue Supports zero copy transfers Can send and receive from HWIs SWIs and TSKs Notification mechanism is specified by application Allows QoS quality of service on...

Page 218: ...ment typedef struct MyMsg MSGQ_MsgHeader header MyMsg The MSGQ API uses the MSGQ_MsgHeader internally Your application should not modify or directly access the fields in the MSGQ_MsgHeader The MSGQ module has the following components MSGQ API Applications call the MSGQ functions to open and use a message queue object to send and receive messages For an overview see MSGQ APIs on page 17 For details...

Page 219: ...ansports will be provided in a future document 6 5 1 MSGQ APIs The MSGQ APIs are used to open and close message queues and to send and receive messages The MSGQ APIs shield the application from having to contain any knowledge about transports and allocators The following figure shows the call sequence of the main MSGQ functions Figure 6 5 MSGQ Function Calling Sequence The reader calls the followi...

Page 220: ...le in the tcf file POOL_config variable in application code See the DSP BIOS Application Programming Interface Guide for your platform for information about setting the properties mentioned in this list An application must provide a filled in MSGQ_config variable in order to use the MSGQ module MSGQ_Config MSGQ_config The MSGQ_Config type has the following structure typedef struct MSGQ_Config MSGQ...

Page 221: ..._TransportObj Array of transport objects The fields of each object must be initialized numMsgqQueues Uint16 Length of the msgqQueues array numProcessors Uint16 Length of the transports array startUninitialized Uint16 Index of the first message queue to initialize in the msgq Queue array This should be set to 0 errorQueue MSGQ_Queue Message queue to receive transport errors Initialize to MSGQ_INVAL...

Page 222: ... for the message is allocated An allocator is an instance of an implementation of the allocator interface An application may instantiate one or more instances of an allocator The POOL module describes standard interface functions that allocators must provide The allocator interface functions are called internally by the MSGQ module and not by user applications A simple static allocator called STAT...

Page 223: ...ication mechanism without changing the application except for the configuration of the transport A transport is an instance of an implementation of the transport interface There is an array of transports on each processor There is at most one transport between any two processors This array is based on processor IDs So the first element the 0th index of the transport array on each processor contain...

Page 224: ...l be provided in a future document The protocol between transports is transport specific but must have the ability to locate message queues and send messages across the physical boundary The following figure shows an example of sending a message to a message queue on another processor Figure 6 7 Remote Transport Processor Transport Array Processor 0 0 MSGQ_NOTRANSPORT transport 1 transport to proc...

Page 225: ...hen a message is allocated the ID of the allocator is embedded into the MSGQ_MsgHeader portion of the allocated message This makes it easy to free the message later That is the application does not need to remember which allocator was used to allocate the message Some transports are copy based When such transports send a message to a remote processor the message is copied to the physical link for ...

Page 226: ...B must also allocate messages of 64 bytes if messages are flowing in both directions The underlying allocation mechanisms may be different but the sizes of the messages must be the same Routing is the ability to send a message from one processor to another processor via an intermediate processor Routing is needed when there is no physical link between two processors Routing is not directly support...

Page 227: ...rmation Messaging is generally performed with multiple writers and one reader There are several differences between MSGQ QUE and MBX Each module has its pros and cons Ultimately it is up to the application designer to decide which one fits their application best The following list describes issues to consider when making a decision Multi Processor Support MSGQ offers multi processor support Neithe...

Page 228: ...e MBX module has a fixed length and number of messages per mailbox These values are specified when the mailbox is created Both QUE and MSGQ allow for variable sized messages They have no maximum number of messages that may be waiting to be received Complexity and Footprint The MSGQ module offers many advanced features However this comes with added complexity and a larger footprint For applications...

Page 229: ..._put operations for output The code for reading data might look like Example 6 5 Example 6 5 Reading Data Through a Host Channel Each host channel can specify a data notification function to be performed when a frame of data for an input channel or free space for an output channel is available This function is triggered when the host writes or reads a frame of data HST channels treat files as 16 o...

Page 230: ...e host ultimately depends on the choice of physical data link the HST Channel interface remains independent of the physical link The HST Manager in the configuration allows you to choose among the physical connections available On the C55x and C6000 platforms the host PC triggers an interrupt to transfer data to and from the target This interrupt has a higher priority than SWI TSK and IDL function...

Page 231: ...I O Reading and Writing Streams 7 7 7 4 Stackable Devices 7 16 7 5 Controlling Streams 7 22 7 6 Selecting Among Multiple Streams 7 23 7 7 Streaming Data to Multiple Clients 7 25 7 8 Streaming Data Between Target and Host 7 27 7 9 Device Driver Template 7 28 7 10 Streaming DEV Structures 7 30 7 11 Device Driver Initialization 7 33 7 12 Opening Devices 7 34 7 13 Real Time I O 7 38 7 14 Closing Devic...

Page 232: ...n this chapter related to using SIO streams is still relevant if you are using SIO streams with IOM mini drivers Chapter 6 describes the device independent I O operations supported by DSP BIOS from the vantage point of an application program Programs indirectly invoke corresponding functions implemented by the driver managing the particular physical device attached to the stream using generic func...

Page 233: ...e internal driver functions can rely on virtually all of the capabilities supplied by DSP BIOS ranging from the multitasking features of the kernel to the application level services Drivers use the device independent I O interface of DSP BIOS to communicate indirectly with other drivers especially in supporting stackable devices Generic I O Operation Internal Driver Operation SIO_create name mode ...

Page 234: ...output streams exchange buffers with the device using the atomic queues device todevice and device fromdevice Figure 7 2 Device Driver and Stream Relationship For every device driver you need to write Dxx_open Dxx_idle Dxx_input Dxx_output Dxx_close Dxx_ctrl Dxx_ready Dxx_issue and Dxx_reclaim SIO_create SIO_ctrl SIO_get SIO_put todevice fromdevice SIO Device Driver Stream Device open ctrl issue r...

Page 235: ... function to delete statically created streams 7 2 2 Creating and Deleting Streams Dynamically You can also create a stream at run time with the SIO_create function as shown in Example 7 1 Example 7 1 Creating a Stream with SIO_create SIO_create creates a stream and returns a handle of type SIO_Handle SIO_create opens the device s specified by name specifying buffers of size bufsize Optional attri...

Page 236: ...IM no stream buffers are allocated since the creator of the stream is expected to supply all necessary buffers SIO_delete shown in Example 7 2 closes the associated device s and frees the stream object If the stream was opened using the SIO_STANDARD streaming model it also frees all buffers remaining in the stream User held stream buffers must be explicitly freed by the user s code Example 7 2 Fre...

Page 237: ...kes the number of bytes in the output buffer Example 7 3 Inputting and Outputting Data Buffers Note Since the buffer pointed to by bufp is exchanged with the stream the buffer size memory segment and alignment must correspond to the attributes of stream SIO_issue and SIO_reclaim are the calls that implement the Issue Reclaim streaming model as shown in Example 7 4 SIO_issue sends a buffer to a str...

Page 238: ...o block and wait for a buffer The Issue Reclaim streaming model also provides greater determinism in buffer management by guaranteeing that the client s buffers are returned in the order that they were issued This allows a client to use memory from any source for streaming For example if a DSP BIOS task receives a large buffer that task can pass the buffer to the stream in small pieces simply by a...

Page 239: ...dependent of the buffer size In each case the actual physical buffer has been changed by SIO_get The important implication is that you must make sure that any references to the buffer used in I O are updated after each operation Otherwise you are referencing an invalid buffer SIO_put uses the same exchange of pointers to swap buffers for an output stream SIO_issue and SIO_reclaim each move data in...

Page 240: ...e log buffer trace The output for Example 7 5 appears as sine wave data in Figure 7 4 Example 7 5 Basic SIO Functions siotest1 c In this program a task reads data from a DGN sine device and prints the contents of the data buffers to a log buffer The data exchange between the task and the device is done in a device independent fashion using the SIO module APIs The stream in this example follows the...

Page 241: ... streamTask Void doStreaming Uns nloops Int i j nbytes Int buf status SIO_staticbuf input Ptr buf if status SYS_ok SYS_abort could not acquire static frame for i 0 i nloops i if nbytes SIO_get input Ptr buf 0 SYS_abort Error reading buffer d i LOG_printf trace Read d bytes nBuffer d data nbytes i for j 0 j nbytes sizeof Int j LOG_printf trace d buf j LOG_printf trace End SIO example 1 ...

Page 242: ...the configuration streamTask reads buffers from a DGN sine device as before but now it sends the data buffers to outputStream rather than printing the contents to a log buffer The stream outputStream sends the data to a DGN user device called printData Device printData takes the data buffers received and uses the DGN_print2log function to display their contents in a log buffer The log buffer is sp...

Page 243: ... SIO_Handle output outputStream Void doStreaming Uns nloops Void doStreaming Arg nloops_arg Int i nbytes Int buf Long nloops Long nloops_arg if SIO_staticbuf input Ptr buf 0 SYS_abort Error reading buffer for i 0 i nloops i if nbytes SIO_get input Ptr buf 0 SYS_abort Error reading buffer d Arg i if SIO_put output Ptr buf nbytes 0 SYS_abort Error writing buffer d Arg i LOG_printf trace End SIO exam...

Page 244: ...Example 7 7 is functionally equivalent to Example 7 6 However the streams are now created using the Issue Reclaim model and the SIO operations to read and write data to a stream are SIO_issue and SIO_reclaim In this model when streams are created dynamically no buffers are initially allocated so the application must allocate the necessary buffers and provide them to the streams to be used for data...

Page 245: ...nloops i Issue an empty buffer to the input stream if SIO_issue input buf SIO_bufsize input NULL 0 SYS_abort Error issuing buffer d i Reclaim full buffer from the input stream if nbytes SIO_reclaim input buf arg 0 SYS_abort Error reclaiming buffer d i Issue full buffer to the output stream if SIO_issue output buf nbytes NULL 0 SYS_abort Error issuing buffer d i Reclaim empty buffer from the output...

Page 246: ... an example a program implementing an algorithm that inputs and outputs a stream of fixed point data using a pair of A D D A converters However the A D D A device can take only the 14 most significant bits of data and the other two bits have to be 0 if you want to scale up the input data Instead of cluttering the program with excess code for data conversion and buffering to satisfy the algorithm s...

Page 247: ...am calls the SIO data streaming functions Figure 7 6 The Flow of Empty and Full Frames 7 4 1 Example SIO_create and Stacking Devices Example 7 9 illustrates two tasks sourceTask and sinkTask that exchange data through a pipe device sourceTask is a writer task that receives data from an input stream attached to a DGN sine device and redirects the data to an output stream attached to a DPI pipe devi...

Page 248: ...device you must first enter a configured terminal device in the Device Control Parameter property The name of the terminal device must be preceded by a slash character In the example we use sineWave where sineWave is the name of a configured DGN terminal device Then select the stacking device scale from the dropdown list in the Device property The configuration will not allow you to select a stack...

Page 249: ...d h include dtr h include log h include mem h include sio h include sys h include tsk h define BUFSIZE 128 ifdef _62_ define SegId IDRAM extern Int IDRAM MEM segment ID defined with conf tool endif ifdef _55_ define SegId DATA extern Int DATA MEM segment ID defined with conf tool endif extern LOG_Obj trace LOG object created with conf tool extern TSK_Obj sourceTask TSK thread objects created via c...

Page 250: ...nloops sink This function forms the body of the sinkTask TSK thread Void sink Uns nloops SIO_Handle input inStreamSink SIO_Handle output outStreamSink Do I O doStreaming input output nloops LOG_printf trace End SIO example 5 doStreaming I O function for the sink and source tasks static Void doStreaming SIO_Handle input SIO_Handle output Uns nloops Ptr buf Int i nbytes if SIO_staticbuf input buf 0 ...

Page 251: ...ou can edit sioTest5 c and change the scaling factor of the DTR_PRMS rebuild the executable and see the differences in the output to myLog A version of Example 7 9 where the streams are created dynamically at runtime by calling SIO_create is available in the product distribution siotest4 c siotest4 cdb ...

Page 252: ...le 7 11 Changing Sample Rate In some situations you can synchronize with an I O device that is doing buffered I O There are two methods to synchronize with the devices SIO_idle and SIO_flush Either function leaves the device in the idled state Idling a device means that all buffers are returned to the queues that they were in when the device was initially created That is the device is returned to ...

Page 253: ...rom several sources The SIO_select mechanism allows a single task to handle all of these sources SIO_select is called with an array of streams an array length and a time out value SIO_select blocks if timeout is not 0 until one of the streams is ready for I O or the time out expires In either case the mask returned by SIO_select indicates which devices are ready for service a 1 in bit j indicates ...

Page 254: ...lling Two Streams SIO_Handle stream0 SIO_Handle stream1 SIO_Handle streamtab 2 Uns mask streamtab 0 stream0 streamtab 1 stream1 while mask SIO_select streamtab 2 0 0 I O would block do something else if mask 0x1 service stream0 if mask 0x2 service stream1 ...

Page 255: ...interrupt level This forces the user to copy data in order to send it to multiple clients This is shown in Example 7 15 Example 7 15 Using SIO_put to Send Data to Multiple Clients Copying the data wastes CPU cycles and requires more memory since each stream needs buffers If you were double buffering Example 7 15 would require eight buffers two for each stream Example 7 16 illustrates the advantage...

Page 256: ...transfers then transfers this buffer of data concurrently The program does not return from the four SIO_reclaims until a buffer is available from all of the streams In summary the SIO_issue SIO_reclaim functions offer the most efficient method for the simultaneous transmission of data to more than one stream This is not a reciprocal operation the SIO_issue SIO_reclaim model solves the scatter prob...

Page 257: ... them DSP BIOS includes a host I O module HST that makes it easy to transfer data between the host computer and target program Each host channel is internally implemented using an SIO stream object To use a host channel the program calls HST_getstream to get the corresponding stream handle and then transfers the data using SIO calls on the stream You configure host channels or HST objects for inpu...

Page 258: ...r details about configuring device drivers including both custom drivers and the drivers provided with DSP BIOS you need to reference the specific device driver 7 9 1 Typical File Organization Device drivers are usually split into multiple files For example dxx h Dxx header file dxx c Dxx functions dxx_asm s optional assembly language functions Most of the device driver code can be written in C Th...

Page 259: ...functions is contained in dxx c This table is used by the SIO module to call specific device driver functions For example SIO_put uses this table to find and call Dxx_issue Dxx_reclaim The table is shown in Example 7 18 Example 7 18 Table of Device Functions dxx h include dev h extern DEV_Fxns Dxx_FXNS Dxx_Params typedef struct device parameters go here Dxx_Params DEV_Fxns Dxx_FXNS Dxx_close Dxx_c...

Page 260: ...l buffer size misc is an extra field which is reserved for use by a device arg is an extra field available for you to associate information with a particular frame of data This field should be preserved by the device cmd is a command code for use with mini drivers that use the IOM model described in the DSP BIOS Driver Developer s Guide SPRU616 The command code tells the mini driver what action to...

Page 261: ...Frame frames from the device In the SIO_STANDARD DEV_STANDARD streaming model SIO_put gets empty frames from this queue and SIO_get gets full frames from here In the SIO_ISSUERECLAIM DEV_ISSUERECLAIM streaming model SIO_reclaim retrieves frames from this queue bufsize specifies the physical size of the buffers in the device queues nbufs specifies the number of buffers allocated for this device in ...

Page 262: ...is possible for a driver to dynamically alter these functions in Dxx_open timeout specifies the number of system ticks that SIO_reclaim will wait for I O to complete align specifies the buffer alignment callback specifies a pointer to a channel specific callback structure The DEV_Callback structure contains a callback function and two function arguments The callback function is typically SWI_andnH...

Page 263: ...nd initializes static driver structures as shown in Example 7 22 Example 7 22 Initialization by Dxx_init Although Dxx_init is required in order to maintain consistency with DSP BIOS configuration and initialization standards there are actually no DSP BIOS requirements for the internal operation of Dxx_init There is in fact no standard for hardware initialization and it can be more appropriate on s...

Page 264: ...segid etc fields in DEV_Obj from parameters and SIO_Attrs passed to SIO_create 4 Create todevice and fromdevice queues 5 If opened for DEV_STANDARD streaming model allocate attrs nbufs buffers of size BUFSIZE and put them on todevice queue 6 Call Dxx_open with pointer to new DEV_Obj and remaining name string using syntax as shown status Dxx_open device 16 7 Validate fields in DEV_Obj pointed to by...

Page 265: ...ies the device by using DEV_match to match the string adc against the list of configured devices The string remainder 16 would be passed to Dxx_open to set the ADC to the correct sampling frequency Dxx_open usually allocates a device specific object that is used to maintain the device state as well as necessary semaphores For a terminating device this object typically has two SEM_Handle semaphore ...

Page 266: ...art on the device params settings passed by SIO_create Second this object is attached to device object Dxx_open returns SYS_OK to SIO_create which now has a properly initialized device object Int Dxx_open DEV_Handle device String name Dxx_Handle objptr check mode of device to be opened if device mode is invalid return SYS_EMODE check device id if device devid is invalid return SYS_ENODEV if device...

Page 267: ...SIO_put which can block by pending on objptr sync When the required output is accomplished SEM_post is called with objpt sync This makes a task blocked in Dxx_output ready to run DSP BIOS does not impose any special constraints on the use of synchronization semaphores within a device driver The appropriate use of such semaphores depends on the nature of the driver requirements and the underlying h...

Page 268: ...rupt by means of an HWI ISR in Figure 7 8 which accumulates the data and determine if more data is needed for the waiting frame If the HWI determines that the required amount of data has been received the HWI transfers the frame to device fromdevice and then call SEM_post on the device semaphore This allows the task blocked in Dxx_reclaim to continue Dxx_reclaim then returns to SIO_get which will ...

Page 269: ...10 posts to objptr sync Dxx_reclaim is unblocked and returns to SIO_reclaim SIO_reclaim then gets the frame from the device fromdevice queue and returns the buffer This sequence is shown in Figure 7 9 and Figure 7 10 Figure 7 9 Placing a Data Buffer to a Stream Figure 7 10 Retrieving Buffers from a Stream SIO_issue outstream bufp nbytes arg SIO_reclaim outstream bufp parg timeout 1 Put full bufp o...

Page 270: ...fromdevice queue then returns Dxx_reclaim calls SEM_pend with the timeout value specified at the time the stream is created either statically or with SIO_create with this value If the timeout expires before a buffer becomes available Dxx_reclaim returns SYS_ETIMEOUT In this situation SIO_reclaim does not attempt to get anything from the device fromdevice queue SIO_reclaim returns SYS_ETIMEOUT and ...

Page 271: ...xx_Handle device object Uns post_count The only time we will wait for all pending data is when the device is in output mode and flush was not requested if device mode DEV_OUTPUT flush first make sure device is started if device is not started device has received data start the device wait for all output buffers to be consumed by the output HWI We need to maintain a count of how many buffers are re...

Page 272: ...s no effect on a device opened for input For a device opened for output however the flush parameter is significant If flush is TRUE any pending data is thrown away If flush is FALSE the Dxx_idle function does not return until all pending data has been rendered Don t simply SEM_reset the count here There is a possibility that the HWI had just completed working on a buffer just before we checked and...

Page 273: ...f the next call to retrieve a buffer from the device will not block This usually means that there is at least one available frame on the queue device fromdevice when Dxx_ready returns as shown in Example 7 32 Refer to section 7 6 Selecting Among Multiple Streams page 7 23 for more information on SIO_select Example 7 32 Making a Device Ready If the mode is DEV_INPUT the streaming model is DEV_STAND...

Page 274: ... ready mask Uns ready 0 bit mask of ready streams SEM_Handle sem local semaphore SIO_Handle stream pointer into streamtab For efficiency the real SIO_select doesn t call SEM_create but instead initializes a SEM_Obj on the current stack sem SEM_create 0 NULL stream streamtab for i n i 0 i stream call each device ready function with sem if Dxx_ready device sem ready 1 if ready wait until at least on...

Page 275: ...wise SIO_select pends on the ready semaphore until at least one device is ready or until the time out has expired Consider the case where a device becomes ready before a time out occurs The ready semaphore is posted by whichever device becomes ready first SIO_select then calls Dxx_ready again for each device this time with sem NULL This has two effects First any additional Dxx device that becomes ...

Page 276: ...copying stacking devices The in place stacking device performs in place manipulations on data in buffers The copying stacking device moves the data to another buffer while processing the data Copying is necessary for devices that produce more data than they receive for example an unpacking device or an audio decompression driver or because they require access to the whole buffer to generate output...

Page 277: ...er All data processing is done in a single buffer This is a relatively simple device but it is not as general purpose as the copying stacking driver Figure 7 13 In Place Stacking Driver Current Device To From Physical Device fromdevice queue todevice queue Underlying Device fromdevice queue todevice queue Reclaim Issue Current Device fromdevice queue todevice queue ...

Page 278: ...ce in a copying stacking device the task side buffers can be a different size than the device side buffers Also care is taken to preserve the order of the buffers coming into the device so the SIO_ISSUERECLAIM streaming model can be supported Figure 7 14 Copying Stacking Driver Flow Current Device fromdevice queue todevice queue Underlying Device fromdevice queue todevice queue Input Processing in...

Page 279: ...d use 4 4 BIOS_init 2 24 2 25 BIOS_start 2 25 BIOSREGS memory segment 1 12 Bool 1 11 boot c 2 24 buffer length 3 19 buffer size LOG objects 3 15 buffers and devices 7 7 and streams 7 7 exchanging 7 4 7 8 7 9 C C run time 4 21 C 2 28 calloc 2 22 catastrophic failure 4 40 channels 6 27 Char 1 11 class constructor 2 30 class destructor 2 30 class methods 2 29 clear 3 22 CLK default configuration 4 74...

Page 280: ...rame structure 7 30 idling 7 41 7 42 7 43 7 44 See also Dxx_idle initialization of 7 33 opening 7 34 parameters 7 29 readying 7 43 See also Dxx_ready SIO_select stackable 7 46 stacking 7 16 7 17 synchronizing 7 22 terminating 7 46 typedef structure 7 35 virtual 7 17 DSP BIOS Analysis Tools 1 8 DSP BIOS Configuration Tool 1 6 2 11 files generated 2 19 dxx h 7 28 Dxx_ctrl 7 43 Dxx_idle 7 41 example ...

Page 281: ...ion SYS_abort 5 12 SYS_exit 5 12 handle 2 17 hardware interrupt and SEM_post or SEM_ipost 4 59 hardware interrupts 4 2 counting 3 32 statistics 3 34 typical frequencies header files 2 18 including 1 9 naming conventions 1 9 heap end 3 14 size 3 14 start 3 14 high resolution times 4 72 hook functions 4 44 HOOK module 4 44 HOOK_KNL object 4 44 Host Channel Manager 3 18 host channels 6 27 host clear ...

Page 282: ...ne 2 24 interrupt service table 2 24 interrupts 4 11 inter task synchronization 4 59 IPRAM memory segment 1 12 IPROG memory segment 1 12 ISR 2 24 3 29 HWI_enter 4 21 HWI_exit 4 21 Issue Reclaim streaming model 7 6 7 7 7 8 7 31 7 39 IVPD 2 26 IVPH 2 26 J JTAG 3 40 3 41 K kernel 1 5 KNL_run 1 10 L LabVIEW 3 38 large model 2 15 LgInt 1 11 LgUns 1 11 linker command file 2 10 2 22 options 2 23 linker s...

Page 283: ...e 6 15 MSGQ_config variable 6 18 MSGQ_TransportObj structure 6 19 multi processor messaging 6 15 multitasking See tasks N name mangling 2 28 2 29 name overloading 2 29 namespace and device parameters 7 29 and devices 7 17 naming conventions 1 9 2 28 near keyword 2 15 nmti 3 33 notify function 6 27 notifyReader function 6 8 notifyWriter function 6 8 NULL 1 11 O object pre configured 1 7 SWI 4 26 ob...

Page 284: ...Time versus Cyclic Debugging 3 2 Refresh Window 3 22 register monitoring 3 34 register context extending 4 44 registers monitoring in HWI 3 34 saving and restoring 4 24 saving when preempted 4 36 reserved function names 1 10 ROV 3 10 RTA Control Panel 3 4 3 28 RTA tools 3 3 RTA_dispatcher 4 50 RTA_F_dispatch function 1 10 RTDX 2 22 3 38 data flow 3 40 header files 2 10 host library 3 40 rts src 2 ...

Page 285: ...ack overflow check 4 43 stack pointer 3 33 stack size and task objects 4 39 stackable devices writing 7 46 standard streaming model 7 6 7 31 and buffers 7 6 implementing 7 7 standardization 1 3 startup 2 24 startup sequence 2 24 static configuration 1 6 2 11 static objects 2 15 statistics 3 15 accumulating 3 23 gathering 4 78 performance 3 15 units 4 78 Statistics Data tool 3 9 3 21 Statistics Man...

Page 286: ...cheduling 4 42 task objects 4 39 terminating See TSK_exit TSK module 4 39 Tconf script 1 6 2 11 textual scripting 1 6 2 11 thread 1 4 preemption 4 9 priorities 4 7 type comparisons 4 5 threads choosing types 4 4 time idle 3 29 work 3 29 timer interrupt rate 4 72 timer counter register 4 72 time slicing scheduling 4 46 timing methods 4 71 total 3 21 trace state 3 27 performance 3 15 tracing 3 15 tr...

Page 287: ...Index 9 Index Void 1 11 W words data memory 3 15 of code 1 5 wrapper function 2 29 ...

Page 288: ...Index 10 Index ...

Search results

Summary of Contents for TMS320 Series

Reviews:

Related manuals for TMS320 Series

Brands by name

Popular brands

Texas Instruments TMS320 Series, User Manual

Search results

Summary of Contents for TMS320 Series

Reviews:

Related manuals for TMS320 Series

Brands by name

Popular brands