PurePath Studio GDE User s Guide Graphical Development Environment for TAS3xxx Digital Audio Processors. User's Guide. Mixed Signal Audio Applications

Transcription

1 PurePath Studio GDE User s Guide Graphical Development Environment for TAS3xxx Digital Audio Processors U s e r ' s G u i d e User's Guide May 2008 Mixed Signal Audio Applications

2 IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements, improvements, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All products are sold subject to TI s terms and conditions of sale supplied at the time of order acknowledgment. TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with TI s standard warranty. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by government requirements, testing of all parameters of each product is not necessarily performed. TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and applications using TI components. To minimize the risks associated with customer products and applications, customers should provide adequate design and operating safeguards. TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right, copyright, mask work right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services are used. Information published by TI regarding third-party products or services does not constitute a license from TI to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI. Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. Reproduction of this information with alteration is an unfair and deceptive business practice. TI is not responsible or liable for such altered documentation. Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements. Following are URLs where you can obtain information on other Texas Instruments products & application solutions: Products Applications Amplifiers amplifier.ti.com Audio Data Converters dataconverter.ti.com Automotive DSP dsp.ti.com Broadband Interface interface.ti.com Digital Control Logic logic.ti.com Military Power Mgmt power.ti.com Optical Networking Microcontrollers microcontroller.ti.com Security Telephony Video & Imaging Wireless Mailing Address: Texas Instruments Post Office Box Dallas, Texas Copyright 2006, Texas Instruments Incorporated May 2008 Mixed Signal Audio Applications

3 Preface Read This First About This Manual This manual describes the PurePath Studio Graphical Development Environment for Texas Instruments TAS3xxx family of Programmable Digital Audio Processors How to Use This Manual This document contains the following chapters: Chapter 1 PurePath Studio GDE Overview Chapter 2 Understanding the GDE User Interface Chapter 3 Developing a Process Flow Chapter 4 Configuring the TAS3xxx Device Chapter 5 Integrated Development Environment Chapter 6 Developing Custom Components Additional Documentation TAS3xxx Data Manual TAS3xxx DSP Instruction Set Reference General TAS3xxx Application Notes Trademarks PurePath Studio TM is trademark of Texas Instruments. iii

4 Contents READ THIS FIRST...III CONTENTS... IV FIGURES... VI TABLES... VII PUREPATH STUDIO GDE OVERVIEW... 2 UNDERSTANDING THE GDE USER INTERFACE THE COMPONENT WINDOW Frameworks Input/Output Volume Tone Mixers Filters Effects Dynamic Processing Basic DSP Level Detectors TI Algorithms Signal Generators Third Party... Error! Bookmark not defined User Defined THE DIAGRAM WINDOW (GDE PALLET) THE PROPERTIES WINDOW THE RESOURCES WINDOW THE OUTPUT WINDOW... 5 DEVELOPING A PROCESS FLOW BUILDING THE PROCESS FLOW IN THE GDE PALLET COMPONENT ALIASING DEFINING FILTER TYPES AND COEFFICIENTS The Filter Data Tab The Frequency Response Graph Tab The Phase Response Graph Tab CONFIGURING THE TAS3XXX DEVICE CONFIGURATION SCRIPTS GDE SOFTWARE REMAPPING I 2 C OVERVIEW WINDOW I 2 C COMMAND TOOL PROBE POINTS The Configuration Tab The Chart Tab The Data Tab I 2 C RAM TOOL I 2 C Tab iv

5 4.6.2 Peek / Poke Tab INTEGRATED DEVELOPMENT ENVIRONMENT EDITING DSP ASSEMBLY LANGUAGE USING THE IDE Bookmarks Window Viewing options Code Syntax Coloring Command Completion ASSEMBLING, BUILDING, AND DOWNLOADING Instantiating Assembly Templates Assembling the Source Files Building an EEPROM Image Downloading to the EVM SIMULATING DSP ASSEMBLY CODE WITH THE IDE WAV FILE INPUT/OUTPUT DEVELOPING CUSTOM COMPONENTS OVERVIEW OF A COMPONENT GDE GENERATED CODE OVERVIEW The DSP Application Overview Code Generation Macros %%prop() %%If (), %%else(), and %%endif %%define() %%defined() ## comments CREATING A NEW COMPONENT FROM SCRATCH CREATING A NEW COMPONENT FROM AN EXISTING COMPONENT TEMPLATE CREATING A NEW COMPONENT FROM AN EXISTING PROCESS FLOW PUBLISHING A COMPONENT Component Publisher Main Page Design, Runtime, and I 2 C Properties Component Recepies Component File Manifest Pop-Up Graphical User Interface Component Help Files v

6 Figures FIGURE 3-1: PLACING A DEVICE FRAMEWORK INTO THE GDE PALLET... 7 FIGURE 3-2: PLACING CORRESPONDING TAS3XXX INPUT/OUTPUT COMPONENTS INTO THE PALLET.. 8 FIGURE 3-3: PLACING A STEREO MUX INTO THE GDE PALLET... 9 FIGURE 3-4: LINKING INPUT AND OUTPUT PORTS IN THE PALLET... 9 FIGURE 3-5: SELECTIVE FREQUENCY FILTER OF TWO AUDIO CHANNELS FIGURE 3-6: COMPLETE SYSTEM PROCESS FLOW FIGURE 3-7: CONFIGURING A COMPONENT AS AN ALIAS FIGURE 3-8: FILTER DATA TAB OF THE BIQUAD GUI FIGURE 3-9: FREQUENCY RESPONSE GRAPH TAB OF THE BIQUAD GUI FIGURE 3-9: PHASE RESPONSE GRAPH TAB OF THE BIQUAD GUI FIGURE 4-1:PUREPATH STUDIO I 2 C TOOLS MENU FIGURE 4-2: I 2 C OVERVIEW WINDOW FIGURE 4-3: I 2 C COMMAND TOOL FIGURE 5-2: INSTANTIATE TEMPLATE COMMAND IN THE IDE BUILD OPTIONS MENU FIGURE 5-3: ASSEMBLE COMMAND IN THE IDE BUILD OPTIONS MENU FIGURE 5-4: BUILD IMAGE COMMAND IN THE IDE BUILD OPTIONS MENU FIGURE 5-5: IDE TOOLS OPTIONS FIGURE 5-6: LOAD IMAGE COMMAND IN THE IDE DEBUG MENU FIGURE 5-7: IDE SIMULATOR OVERVIEW FIGURE 5-8: EXIT DEBUGGER COMMAND IN THE IDE DEBUG MENU FIGURE 5-9:.WAV FILE I/O WINDOW FIGURE 6-1: COMPONENT FILES RELATIONSHIP FIGURE 6-2: COMPONENT PUBLISHER MAIN PAGE FIGURE 6-3: COMPONENT PUBLISHER RUNTIME AND I 2 C PROPERTIES FIGURE 6-4: COMPONENT PUBLISHER RECIPES vi

7 FIGURE 6-5: COMPONENT PUBLISHER FILE MANIFEST Tables TABLE 6-1: COMPONENT PUBLISHER MAIN PAGE DESCRIPTIONS TABLE 6-2: DESCRIPTION OF DESIGN PROPERTIES TABLE 6-3: COMPONENT RECIPE OPTIONS vii

8 Chapter 1 PurePath Studio GDE Overview The PurePath Studio Graphical Development Environment (GDE) is software tool suite developed to aid the user to quickly and easily develop Digital Signal Processor (DSP) assembly language code for Texas Instruments (TI) TAS3xxx Family of Digital Audio Processors. This manual describes how to use PurePath Studio GDE to easily develop custom audio processing algorithms using a wide range of graphical drag-and-drop components ranging from simple algebraic arithmetic to 3 rd Party algorithms to custom developed components. This User s Guide also describes how to create, test, and publish custom components that can be used in developing a signal processing algorithm. This User s Guide assumes that the reader is not familiar with Texas Instruments PurePath Studio Graphical Development Environment nor does it assume the reader has any DSP assembly language programming experience. This User s Guide does assume that the user is familiar with the basic features of the TAS3xxx Digital Audio Processor. PurePath Studio Graphical Development Environment Features Develop DSP assembly language by graphically placing TAS3xxx Framework and reusable audio components into an algorithm pallet. Quickly configure desired properties of audio components via the components property window, and in some cases a custom component GUI. Develop multi component processing by graphically wiring I/O ports of components together Generate and view DSP assembly language code for a Process Flow. Build and download an EEPROM image that can be configured to run on an existing TAS3xxx Evaluation Module Dynamically Control components during run-time execution of the algorithm Read and Write values to registers within the TAS3xxx devices using a GUI Graphically probe, watch, and log nodes of the algorithm during execution. 1-1

9 Chapter 2 Understanding the GDE User Interface The PurePath Studio Graphical Development Environment consists of five main windows: The Component Window, the Diagram Window (often referred to as the GDE pallet), the properties Window, the Resources Window, and the Output Window. Each window can be reshaped, resized, or moved around similar to most applications on a Windows PC. By default, each window is docked to the environment; however the user can configure the windows according to their individual preferences. 2.1 The Component Window The Component window displays all of the available drag-and-drop audio components that are supported by PurePath Studio Graphical Development Environment. It is sectioned into various component category headings in which individual components are stored. The following sections briefly outline the types of components contained within each heading Frameworks The Frameworks heading contains the TAS3xxx application frameworks available from TI. A TAS3xxx application framework defines a device specific code skeleton for an audio processing application, and is utilized by all components within a custom audio processing algorithm. Note: Every diagram must contain an application framework before other components can be added. Only one TAS3xxx framework is allowed per application (Process Flow) Input/Output The Input/Output Heading contains all the input and output audio interfaces of the TAS3xxx Family of Digital Audio Processors. The components within this heading are conveniently broken up by TAS3xxx device number. Note: Only the Input / Output interfaces of the placed TAS3xxx framework may be used. Trying to insert any other Input Output interface will result in an error. Note: Only one instance of an input/output interface may be used per application. By default, the number of ports is configured for two audio channels. If a TAS3xxx device supports more than two channels for the particular I/O Interface, the number of channels is configurable via the component property window. 3

10 2.1.3 Volume The Volume Heading contains component(s) that can dynamically control the volume of the audio Tone The Tone Heading contains component(s) that can be used to control the tone of the audio Mixers The Mixer Heading contains component(s) used to add signals together (mix), switch between multiple input signals (multiplex), or replicate input signals (split). Many of the components have a configurable number of inputs/outputs that can be changed in the properties tab of the component Filters The Filter Heading contains component(s) that can be inserted to act as a frequency or amplitude filters for an audio channel. Both Finite Impulse Response (FIR) and Infinite Impulse Response (IIR) filters are available for use in selective frequency filtering Effects The Effects Heading contains component(s) that can be used to either delay or dither the audio signal Dynamic Processing The Dynamic Processing Heading contains component(s) that can be used to compress the dynamic range of the audio signal at user defined thresholds Basic DSP The Basic DSP Heading contains elementary digital signal processing components Level Detectors The Level Detectors Heading contains component(s) that can be used to detect amplitudes and peaks of an audio signal TI Algorithms The Texas Instruments Heading contains royalty-free component(s) that are used for advanced processing. TI components are available to those registered for the Texas Instruments Mixed Signal Audio & Video Extranet. Note: PurePath Studio GDE does not come shipped standard with this heading. TI Components must be added to the components library before this heading becomes visible Signal Generators The Signal Generators heading contains component(s) that can be used to output a static audio signal. 1-4

11 Initialization Initialization Heading is only available in PurePath Studio GDE version 1.78 or later. These components are a replacement for sending a configuration script via the I2C Command Tool. These components do not need to be connected (wired) to any other components in the GDE Pallet Third Party The Third Party Heading contains component(s) that are supported by 3 rd Party Algorithms. Access to these components usually requires a fee and a license agreement through the 3 rd Party Provider. Note: PurePath Studio GDE does not come shipped standard with this heading. 3 rd Party Components must be added to the components library before this heading becomes visible User Defined The User Defined Heading contains components that are custom developed by the user. Note: Custom components are only available after published components is placed in the component library. 2.2 The Diagram Window (GDE Pallet) The Diagram Window is where the components are dropped and graphically connected to form an audio processing algorithm. The grid size of this window is user configurable and can be changed to one of three different sizes. This window also supports tabs. Tabs can be used to view a number of different pallets at a time, however only the working pallet can be used to program the TAS3xxx Device. 2.3 The Properties Window The Properties Window is where the properties of the selected components are displayed. The configurable parameters in this window depend on the component that is selected. The Properties Window contains both static and dynamic properties of the components. Static Properties values will be shadowed out and cannot be changed by the user. Dynamic property values can contain either a field in which numbers can be entered or a drop down selection window. Dynamic property values can all be changed during the creation of the Process Flow. Additionally, some dynamic properties can be changed during run-time execution. 2.4 The Resources Window The Resource Window displays the amount of resources (physical ram) used in the TAS3xxx device after the DSP assembly code is compiled. This resources window is updated each time new code is generated. 2.5 The Output Window The output window allows the software to communicate with the user by displaying warnings, errors, as well as letting the user know what actions the software is performing. 5

12 Note: Warnings and regular communication strings are displayed in black text, where as errors are displayed in red text. Chapter 3 Developing a Process Flow Any audio processing algorithm that is designed by placing components in the Diagram Window of PurePath Studio is defined as Process Flow and carries as file extension.pfw. A process flow can be as simple as streaming audio from input to output, or as complex as the user s imagination. The developer is only limitation being the amount of physical ram resources of the TAS3xxx device. As outlined in Chapter 2 of this document, the first step in created a process flow is to place one of the available TAS3xxx Device frameworks into the GDE pallet. By placing a framework into the pallet, a user is defining the basic structure of the embedded microcontroller (MCU) and DSP code that will be used to control the device during run time. 3.1 Building the Process Flow in the GDE Pallet Note: This document assumes the user is working with the TAS3308 Digital Audio Processor and will show a general process flow with the TAS3308 Framework, TAS3308 Input / Output Interfaces, and supported components. Developing a Process Flow with any TAS3xxx Device can be accomplished by using the desired application framework and I/O Components. 1-6

13 Figure 3-1: Placing a device Framework into the GDE Pallet After the desired TAS3xxx Framework is placed in the GDE Pallet, the next step is to define which I/O interfaces will be used. A process flow must have at least one input and one output interface defined, however any combination of available I/O components is supported. Note: If the user decides not to use a particular interface of a TAS3xxx Device, the input or output component of the TAS3xxx device does not need to be included in the process flow. Once a TAS3xxx Application Framework and I/O components are placed, the algorithm is developed using available components. This User s Guide will show how to create the follow audio processing algorithm: Algorithm must contain two channels of both digital and analog inputs multiplexed into two channels of audio Algorithm must have four channels of Pulse Width Modulated (PWM) outputs. Two output channels must be Low Pass Filtered with a 1 st Order Butterworth Filter at a cutoff frequency of 24kHz. Algorithm must have a master volume control Note: This formentioned algorithm does not necessarily reflect a useful audio filtering application. It is designed for demonstration purposes only. Developing an algorithm that supports both digital and analog input involves placing a TAS3308ADCIn block and one TAS3308SAPIn block into the GDE Pallet. Additionally, a TAS3308PWMOut block must be defined in the GDE pallet. Figure 3-2 shows the setup. 7

14 Figure 3-2: Placing corresponding TAS3xxx Input/Output Components into the Pallet A multiplexer is now dropped into the GDE pallet to allow the user to select between the digital and analog inputs. PurePath Studio supports two types of Multiplexers: 2-8:1 Multipler and a stereo Multiplexer. For this application, a stereo multiplexer is desired over a single multiplexer to keep the number of components in the GDE pallet to a minimum. The setup can be seen in Figure 3-3. Note: It is always a recommended to keep the number of components in a audio processing algorithm to a minimum as each components requires an I 2 sub-address. The GDE Code Generator can support up to 256 separate I 2 C sub-address. Note: Multiplexers added into a Process Flow are configured select channel one by default. The input source can be selected by simply changing the MuxSelect property to the desired input channel in the Property Window of the component. 1-8

15 Figure 3-3: Placing a Stereo Mux into the GDE pallet. Connecting the input and output ports of components is done by single clicking on the designed output port of the first component then single clicking on the desired input port of the second component. Note: To make connects follow the grid pattern with 90 Angles, the user must snap the link to the grid by single clicking the desired grid locations before connecting the link to the input port of the second component. If the user does not define the path of the connections, PurePath Studio will connect the two ports with the shortest possible link. Figure 3-4: Linking input and output ports in the pallet. Two audio channels can be split into four audio channels by dropping a two channel splitter into the pallet. 9

16 An audio channel can be low pass filtered by inserting either an FIR or IIR filter. This setup is seen in figure 3-5. Figure 3-5: Selective Frequency Filter of two audio channels The algorithm definition is completed by mapping the four processed audio channels to the to the Pulse Width Modulated (PWM) Digital to Analog Converter (DAC). By default, each Input and Output device is placed in the GDE pallet with two ports. The TAS3308 supports up to 6 channels of PWM outputs. Changing the TAS3308PWMOut_1 component to four ports is done by changing the channels setting in the components properties. This is done by single clicking the TAS3308PWMOut_1 component. Note: The number of ports supported by a particular audio interface is defined by the respective TAS3xxx datasheet. Adding a master volume control is accomplished by inserting a two channel volume control component between the input and output of the processing flow. Note: By default, any volume control block will attenuate the audio signal by the maximum amount when the process flow is executed. It is up to the user to change the attenuation of the volume block (in db) to the desired level. 1-10

17 3.2 Component Aliasing Figure 3-6: Complete System Process Flow Each instance of a component is assigned its own instance designator. During code generation, The GDE maps each instance of a component to an I 2 C sub-address. For advanced process flows with hundreds of components, it may become necessary for an I 2 C subaddress to be freed up in order to drop a new component into the GDE pallet. Aliasing allows the GDE to assign a single I 2 C sub-address to two or more instances of a particular component. Aliasing works by assigning the same I 2 C sub-address to two or more components in the GDE pallet, thereby allowing aliased components to receive the same information from the TAS3xxx M8051 MCU during an I 2 C transaction. Figure 3-6 shows Biquad_2 to be an alias of Biquad_1. As a result, if the GDE is used to update the filter coefficients of Biquad_1, Biquad_2 will also receive the same update. To make Biquad_2 an alias of Biquad_1, the AliasOf property of Biquad_2 should be changed from None to Biquad_1. This is done in the properties window of Biquad_2, and can be seen in Figure

18 Figure 3-7: Configuring a component as an alias 3.3 Defining Filter Types and Coefficients Biquad Digital Filter Coefficients can be assigned to the Biquad by the GDE using the Biquad GUI. This GUI is selectable by right clicking the mouse after a Biquad instance is selected. The Biquad GUI consists of three different tabs: The Filter Data Tab, The Frequency Response Graph Tab, and the Phase Response Graph Tab The Filter Data Tab The Filter Data Tab allows the user to specify the type of digital filter implemented, Subtype (Butterworth, Chebychev, Bessel, etc ), Cutoff Frequency and, if applicable, Gain, Bandwidth, and Q of a digital filter. The type and Subtype of filter are available from drop down menus. All other information is manually typed into the corresponding window. Note: Each Biquad can contain one or more digital filters. The Filter Creation Tool will add additional rows to the GUI if more filters are specified. Once the filter parameters are input by the user, filter coefficients are automatically generated and populated. These coefficients are available for viewing in the properties window of the Biquad. Updates to any of the parameters in the GUI will also automatically update once the settings are applied. 1-12

19 Figure 3-8: Filter Data Tab of the Biquad GUI The Frequency Response Graph Tab Once the desired filter parameters are entered, the frequency response graph allows the user to visually see the ideal frequency response of the filter. If the frequency response does not meet the filter design requirements, the frequency response of the filter may be visually adjusted by using the mouse until adjust the response. Note: When changing the frequency response using this tab, the filter coefficients are automatically updated once the new settings are applied. 13

20 Figure 3-9: Frequency Response Graph Tab of the Biquad GUI The Phase Response Graph Tab The Phase Response of the digital filter is also visually available via the Phase Response Graph Tab. Figure 3-9: Phase Response Graph Tab of the Biquad GUI 1-14

21 Chapter 4 Configuring the TAS3xxx Device 4.1 Configuration Scripts Ts mentioned above, PurePath Studio GDE aids the user to easily develop the desired DSP Assembly language. Additionally PurePath Studio GDE also configures the program RAM of the embedded M8051 MCU inside each TAS3xxx Device. Each ESFR register configuration is reset to the default settings after a device reset. If the user wishes to use the TAS3xxx device in a different manner, a configuration file must be send to the device to configure it for desired operation. Note: Future Versions of PurePath Studio (V1.78 and later) will include a drag-and-drop configuration file that will replace the traditional configuration script. These drag-and-drop configuration files will have the appearance of a component and can be configured in the properties window. Note: The default settings for the ESFR registers in each device can be found in the respective TAS3xxx Data Manual. 4.2 GDE Software Remapping The Graphical Development Environment allows components placed in the pallet to be dynamically controlled through the slave I 2 C port of the TAS3xxx Device. A consequence of this dynamic control is that each component needs to be addressable by the host I 2 C controller. This addressability is accomplished by assigned each component placed in the pallet an I 2 C sub-address. The TAS3xxx Data manuals have an I 2 C sub-address register Table listed that allows a user to configure various hardware blocks of the device. This registers in this table are not physical hardware registers, rather are software registers that interface with the embedded MCU. When executing code in the ROM, the I 2 C commands send to these registers are interpreted by the I 2 C interface and the MCU. Once interpreted, the MCU executes code that uses the ESFRs of the Device to communicate to the DSP core and provide overall control of the device. When the GDE generates an EEPROM Image, an MCU program ram block is included within the Image. Assuming that the image successfully downloads to the device, the MCU program counter executes the ram code that is downloaded. A result of this is that many of the I 2 C register subaddresses which were defined in the ROM code may not necessarily have a handler function in the ram code (depending on the configuration of the Framework). PurePath Studio GDE comes equipped with an I 2 C Overview window which allows the user to see the usage of all the I 2 C sub-address of the components after they are placed in the GDE pallet and the assembly language has been created. This I 2 C Overview window is available under the Tools Menu of the GDE. 15

22 Figure 4-1:PurePath Studio I 2 C Tools Menu Important: If configuring the device without the use of PurePath Studio GDE, the functions associated with the I 2 C register sub-address listed in each TAS3xxx datasheet will be addressable. If you use PurePath Studio GDE to program the device, some of the I 2 C functions listed in the datasheet may no longer be valid as the handler functions may not be included in the Framework.To determine which I2C registers are still valid, consult the I 2 C Overview Window. 4.3 I 2 C Overview Window The I 2 C Overview Window shows the I 2 C sub-address mapping after the DSP assembly code as been generated by the GDE Figure 4-2: I 2 C Overview Window As an additional feature, the I 2 C Overview Window also shows if the GDE has assigned aliases to any components, or if there are non-aliased components that share the same I 2 C Address. Aliased 1-16

23 components will show up with blue text, non-aliased components that share the same I 2 C address will show up in red text. Note: Non-aliased components that share the same I 2 C address will generate an error. If any I 2 C subaddresses show up in red, simply click the Redo I 2 C Addresses button to redistribute the I 2 C subaddresses in the GDE. 4.4 I 2 C Command Tool The PurePath Studio GDE has an integrated I 2 C Command Tool which allows the user to send commands to the device. These commands are primarily used to configure the TAS3xxx device for desired operation (V1.76 or earlier), however can be used to change the operation of the device during execution of an audio processing algorithm. The I 2 C Command Tool allows the user to send the command file the TAS3xxx Device after each device reset by clicking the Execute on reset box. Additionally, the commands can be sent to the TAS3xxx device in real time by clicking the Execute Now button. Successful or un-successful execution of the command file will be verified by the Output Window in the GDE. 4.5 Probe Points Figure 4-3: I 2 C Command Tool Probe Points are useful tools when debugging or simulating code in the GDE. Probe Points allow the user to view ram on the EVM board during run-time execution of a Process Flow. There are three main tabs in the Probe Point Tool: The Configuration Tab, the Chart Tab, and The Data Tab The Configuration Tab The configuration tab allows users to configure the probe points. Note: Configuration of probe points must be done before data collection has started Selection of the data source is done via the source pull down menu, and the specification of the subaddress is done via the Address column. Once the data is collected, it can be also be output to a file The Chart Tab The chart tab can be used is visually view a selected data point vs time in as data is being collected. 17

24 4.5.3 The Data Tab The data tab can be used to view the data points as numbers. 4.6 I 2 C ram Tool The I 2 C ram tool can be used to Read or Write register values within the TAS3xxx Device during operation. There are two tabs associated with this tool: The I 2 C Tool, and the Peek/Poke Tool I 2 C Tab The I 2 C Tab is used to Read and Write the contents of any I 2 C sub-address that is listed in the I 2 C Overview Window once the device has been programmed using PurePath Studio GDE. Important: This tool is only recommended to be used during run-time operation of a Process Flow. Trying to read or write to the I 2 C ram tool while the device is not running may result in an erroneous value or no change Peek / Poke Tab The Peek / Poke Tab is a general purpose ram tool that can look at registers in MCU Internal ram, MCU External ram, MCU Special Function Registers, DSP Program ram, DSP Data ram, DSP Delay ram, or DSP Coefficient ram. Each of these memories is logically separate from each other. 1-18

25 19

26 Chapter 5 Integrated Development Environment The Integrated Development Environment (IDE) allows users to assemble, build, and execute code for the TAS3xxx Family of Devices. Additionally, the IDE allows the user to simulated code with the built in simulator, generate an EEPROM image, and downloaded the EEPROM image to any of the TAS3xxx Evaluation Modules. Additionally, the IDE can be used with the Component Publisher which allows user create, test, and publish their own custom components to use in a Process Flow. Figure 5-1: IDE Editing Window 1-20

27 5.1 Editing DSP Assembly Language using the IDE Editing code in the IDE takes place in the editing window. This window allows the user to edit a segment of code as if it were a text document. Text and code can be Cut, Copied, and Pasted within the Editing window. The developer can also highlight a particular segment of code, replace it, and insert code Bookmarks The editing window also supports the functionality to place bookmarks at various points of the assembly code. Bookmarks allow users to quickly jump to a specified segment of code with the click of a mouse Window Viewing options The IDE editing window can also be split into independent viewing planes. This feature allows users to view a particular section of code in the top half of the window while simultaneously editing another in the bottom half. Alternatively, the IDE also supports tabbed editing of multiple files in the same editing window. These tabs can either be docked to the IDE background, or can be left floating Code Syntax Coloring The IDE supports syntax color coding. The feature visually segregates Assembly Code Comments, Assembly Op Codes, Numbers, Assembly Directives, DSP instruction mnemonics, NOPs, Assembly labels, and Text in different user configurable colors Command Completion The IDE supports command completion. This feature completes the command after the user types the first few letters of that command. See the IDE help file for more information regarding command completion. 5.2 Assembling, Building, and Downloading Instantiating Assembly Templates The IDE can instantiate assembly template files (.asmx files) by running the Template Instantiator Program. This program replaces the %%prop() reference with an instance value during GDE code generation. This option is available via the IDE build menu. Figure 5-2: Instantiate Template command in the IDE Build Options Menu Note: In order to run the template instantiator, the property references must be defined with the %%define() commands earlier in the assembly template. 21

28 5.2.2 Assembling the Source Files Once the source file is ready, it can be build into an object file by executing the build option. Any errors and warnings from the assembler will appear in the output Window. Clicking on an error or warning in the output window will highlight the corresponding line within the text editor window. This option is available via the IDE build menu. Note: The object file created by assembling the code in the source window will be created in the same directory in which the source code is saved. Figure 5-3: Assemble Command in the IDE Build Options Menu Building an EEPROM Image If the source file is assembled without any errors, the corresponding object file can be quickly built into an EEPROM image by selecting the build option under the build menu. This option is available via the IDE build menu. Note: The EEPROM image created by building the assembly code in the source window will be created in the same directory in which the source code is saved. Figure 5-4: Build Image Command in the IDE Build Options Menu Downloading to the EVM To download the EEPROM image to the EVM, the user must first select the EVM Hardware option in the Tools Options. Once this option is selected, the EEPROM image can be simply downloaded to the Evaluation Module by selecting the Load Image options under the IDE Debug menu. Figure 5-5: IDE Tools Options 1-22

29 Figure 5-6: Load Image Command in the IDE Debug Menu 5.3 Simulating DSP Assembly Code with the IDE The IDE has a built in simulator that can support the TAS3xxx DSP assembly code.. The IDE Simulator can be loaded from the IDE. There are two modes with the IDE: Debug mode and Editing Mode. Be default, the IDE is stared in Editing Mode. In Debug Mode, the program ram address of each instruction is listed to the left of the instruction, the current position of the program counter is marked with a green arrow, and the location of the breakpoints are marked with a red stop sign. Figure 5-7: IDE Simulator Overview The IDE can be switched from Debug Mode to Editing Mode by selecting the Exit Debugger option in the IDE Debug Menu. Figure 5-8: Exit Debugger Command in the IDE Debug Menu 23

30 5.4.wav File Input/Output The wave input/output simulator supports the connection of.wav files to each of the DI/DO registers on the PurePath Studio GDE digital input and output components. Each digital input channel can be connected to an uncompressed mono wave file with 16, 20, 24, or 32 bits per sample. The output also supports the same options for the number of bits per sample. The simulator halts when the.wav file is completed, and a value of 0x0 is placed into the DI register. Figure 5-9:.wav File I/O Window Note: Because the.wav File I/O needs to DI and DO registers of PurePath Studio GDE digital input and output components, it cannot be used to test single components; rather it needs to be used as part of a Process Flow that has digital inputs and output components. 1-24

31 Chapter 6 Developing Custom Components Custom Components can be developed by the user to insert as part of a GDE Process Flow. A component is a reusable audio processing block that can be combined with other blocks to build a complete audio processing algorithm using PurePath Studio GDE. All Components are developed using the Integrated Development Environment and then published using the Component Publisher. New component creation can be accomplished in one of the following ways A component can be developed from scratch. A component can be created using an existing component template A component can be created using an existing Process Flow. This chapter outlines the steps needed to create a component from initial development through complete component publication. 6.1 Overview of a Component A component consists of the following files: The Component XML: A component XML defines all the information that the GDE needs to process the component. This includes the component name, number of inputs and outputs, properties, and special tools for processing the component. The Component XML is generated by the Component Publisher. The Component Help File: The component Help File provides additional information about the component that can be displayed by the GDE. This documentation may describe the implementation of the component or provide assistance in using the components in the GDE. The Component Template: The component template is the actual source code for the component. Templates may include DSP assembly code, M8051 C code, or any other source code format that can be used by the Code Generators. Pop-Up Graphical User Interface: The Pop-Up GUI is a graphical interface plug-in to the GDE used for setting properties of the component. Although all components may have their properties edited through the Property Window of the GDE, for some components it is more effective to dedicate a special pop-up graphical interface for editing the properties. Pop-Up GUIs are delivered with the component and launched by the GDE through a right click on the component symbol in the GDE Pallet. Process Flow Controller: A Process Flow Controller is a non-graphical plug-in to the GDE that controls the behavior of the component during build and execution. Process Flow Controllers respond to changes in the component properties and, during execution, communicate those changes to the EVM hardware via the I 2 C bus. 25

32 When a component is published by the component publisher, the above files are compressed into a.zip folder that is placed into the Component Library Folder of PurePath Studio. Figure 6-1 shows a block diagram of how the files are linked with each other. Figure 6-1: Component Files Relationship 6.2 Generated GDE Code Overview The DSP Application Overview The DSP application assembly code produced by the GDE consists of four separate assembly files. These files can be found within the My Process Flows Folder. dsp_main.asm: The main application file. dsp_flow.asm: DSP flow code that is position sensitive with relation to the data flow dsp_calc.asm: DSP calculation code that is performed at the end of each sample. dsp_links.asm: Assembly directives generated by the GDE to link components together. The main two files of the DSP application consists of the flow code and calculation code. Flow code is DSP assembly code whose position is determined by the flow of data within the audio processing application. The arrangement of flow code is determined by the connections defined by the user in the GDE process flow diagram. If component A is placed immediately before component B in the process flow, then the flow code for A will be placed immediately before the flow code for component B. All of the flow code for the application is generated into the file dsp_flow.asm. Calculation code is DSP code whose position can be independent of the data flow within the application. An example of calculation code is auxiliary code that computes coefficient values used by the flow code. Calculation code is placed at the end of the DSP application ram, after any flow code. This placement preserves the low DSP ram for flow code that may need to be the target of branch statements. Calculation code should not contain any labels that are the target of branch statements. Calculation code is generated into dsp_calc.asm. Nearly every component will contain flow code. Components that contain coefficient computations that do not affect the flow of data can place those computations in the flow code section. One example is Volume, whose coefficient calculations are placed in the flow code section. 1-26

33 6.2.2 Code Generation Macros The GDE code generator takes as an input the component template files and produces DSP Assembly and M8051 C code based on the connections defined the in GDE pallet. The generated code can be controlled and modified in the component template files through the use of the following code generation macros %%prop() The GDE code generator replaces the %%prop() macro with the value of the named property for the current component instance. The Syntax is: %%prop(property_name) Example.data %%prop(instanceid)_var This example declares a variable using the value of the component property named InstanceId, which is unique for each instance of a component that exists in the process flow. For a component called Volume1, the variable will be named Volume1_var %%If (), %%else(), and %%endif The GDE code generator can process conditional statements that are placed in a component template. These are commonly used in component templates to handle variable channel inputs. Conditional statements may be nested and contain the following logic operators: <, >, <=, >=, ==,!, +, -, *, / The syntax is: %%if ( expression ) %%endif Or %%if ( expression ) %%else %%endif These macros can be used to conditionally include DSP code in the generated assembly file based on a property value such as Channels. For example:.data %%prop(instanceid)_splitin1_d.data %%prop(instanceid)_splitout1_d %%if (%%prop(channels) > 1).data %%prop(instanceid)_splitout2_d %%endif %%if (%%prop(channels) > 2) 27

34 .data %%prop(instanceid)_splitout3_d %%endif %%if (%%prop(channels) > 3).data %%prop(instanceid)_splitout4_d %%endif This example declares data for a splitter component that takes 1 input and can support 1 to 4 outputs. Based on the value of the property Channels, up to 4 output variables are defined %%define() The %%define() macro can be used to define a property and set the property s value. The syntax is: %%define( property, value ) An example is: %%define( Channels, 2 ) The two most common uses for this construct are: While developing components in the IDE, using the Instantiate Template feature With the %%defined() macro, to define a property after determining that it has not yet been defined in the code stream %%defined() The %% defined() macro can be used to determine if a property has been defined in code. The syntax is: %%defined( property ) The value of %%defined() is either true or false.a common example of using %%defined()is in conjunction with %%define()to write a section of code that is only generated once, no matter how many instances of a component are created: %%if (!%%defined(onceonly) ) %%define(onceonly, true ) ## Code that should be generated only once %%endif comments The -- string can be used to place comments and text inline with the DSP assembly code. 1-28

35 6.3 Creating Custom Components Creating A New Component From Scratch Development of a component by scratch starts with developing a DSP code template using the Integrated Development Environment. DSP code templates are text files that are used the GDE code generator to produce DSP assembly code for a particular instance of the component. The template files may contain Input and Output port declarations, Coefficient and Data declarations, Assembly language instructions, and code generation macros. A DSP code template typically consists of 6 parts. Description of the component: A description of the component is typically done using comments to describe the number of inputs, number of outputs, component name, and any additional information the developer wishes to include. Declaration of the component data input ports and output ports: Port Declarations are done via the.port assembly directive. The Syntax of this directive is available in the help file for the Integrated Development Environment. Declarations of any coefficient or data variables and their initial values: Data and Coefficient Declarations are done via the.data and.coef assembly directives. The Syntax of this directive is available in the help file for the Integrated Development Environment. Declaration of the components control inputs. These declarations are coefficients or data variables that are assigned value through the component publisher. The DSP assembly code which implements the functionality of the component A line of NOPs. This line NOPs should be the last line in the DSP assembly code. The NOPs are used to prevent the next component in the process flow from violating the two instruction cycle wait period between a ram store and valid ram load of the same register.. Note: The contents of a Data or Coefficient ram register is valid two DSP clock cycles after the store instruction has been executed. A template is created by using the Instantiate Template option under the build menu in the IDE. This generated template is used by the GDE code generator to make DSP assembly language code of a Process Flow. Important: It is highly recommended that the developer have a full understanding of the DSP architecture and instruction set before attempting to create a component from scratch. See the TAS3xxx DSP Instruction Set Reference Guide for details about the DSP system architecture Creating A New Component From An Existing Component Note: To create a new component from an existing template, it is recommended that a copy of the existing component DSP assembly code template be moved into a new directory and immediately renamed. This will ensure that the code template of the original component does not get modified. Existing code templates are recognized by an.asmx file extension. Using the copy of the code template, the developer can edit the.port,.data, and.coef assembly directives to match the desired number of inputs and outputs, as well as data and coefficient values used 29

36 by the component. The Syntax of this directives is available in the help file for the Integrated Development Environment. Note: It may be necessary to include additional DSP assembly directives Finally, the assembly code must be changed to implement the desired functionality of the device. To the new developer, it may be helpful to use code from other components in the component cache for references. To Test the component, it is required to define a set of temporary values which reflect the (InstanceId, Channels, DSPCoefBlockStart1, etc.) using the %%Define() Assembler Directive. Optionally, the user may chose to hard code the values into the.asmx file Creating A New Component From An Existing Process Flow To create a new component from an existing process flow, it is recommended that a copy of the existing assembly code be moved into a new directory and immediately renamed. This will ensure that the original assembly code does not get modified so the developer can use it as a reference. Assuming the process flow has been tested, creating a component from a Process Flow is done by optimizing the assembly code produced by the Graphical Development Environment. In particular, it is necessary to make modifications to optimize the code. These modifications include removing intermediate ports definitions, and any unnecessary pipeline information, as well as any unnecessary loads and stores between components. Variable names will also need to be modified. Once the code is modified, it is necessary to add in port definitions, number of channels, etc to the component. After the code has been tested and verified, use the Component Publisher to publish the newly created component. A simple example of how to develop a component from a Process Flow is available in Appendix A. 6.4 Publishing a component The Component Publisher allows you to publish a component to use in a Process Flow. The component publisher creates an XML file to describe the component, then wraps the XML file, component template files, and other referenced files into a.zip file. Publishing a new component using the Component Publisher is completed in five steps. These steps are outlined in the following sections. Note: Once the.zip file is placed in the PurePath Studio Component Library directory, the component will be available to use in the GDE upon restarting PurePath Studio Graphical Development Environment Component Publisher Main Page The main page of the component publisher allows the developer to set values for members of the component class. It also allows the developer to specify included.dlls, icons, and help files. Table 6-1 describes the properties of the Component Publisher Main Page. Property Required Description Component Name Yes Simple Name for the component (without spaces). This name will be used by the GDE in naming component instances. The property is also used by the Component Publisher to name the component s.zip file: 1-30

37 ComponentName_Vendor_version.zip Component Description No One sentence description of the component. Additional descriptions should be placed in the component help HTML file. Vendor Yes Name of the Vendor Version Yes Version of the Component Palette Name Yes Name of the Header in the GDE where the component should be placed. If this pallet does not exist, the GDE will create one. Display Name Yes The name displayed in the GDE Components window Number Of Channels Yes Number of Channels in use by default Fixed Yes A setting of true indicates that the number of audio channels processed by this component is fixed Minimum Yes Minimum number of channels of audio processed by this component. This feature is disabled if Fixed = True Maximum Yes Maximum number o channels of audio processed by this component. This feature is disabled if Fixed = True Fill Color Yes Fill color for the component when displayed in the GDE Graphic Yes A graphic to display on the component symbol in the GDE Large Icon Yes Icon to display in the component pallet for this component. Number Of Input Ports Number Of Output Ports Yes Yes Number of input ports to display on the component symbol in the GDE Number of output ports to display on the component symbol in the GDE Resizable Yes A setting of true indicates that the GDE will resize the component symbol dynamically based on the number of ports used Help File No Name of a.html file to display as help for this component. If a.html file is entered here, it will automatically appear on the File Manifest Tab. If the source path of this file ends in help/, the file will be placed in a directory in the components.zip file called help/ and refereced as such in the published.xml file. Pop Up DLL No Pop-Up DLL name. This name will automatically appear on the File Manifest Tab. Pop Up Text No Text to display in the context menu to describe the available Pop-up GUI 31

38 Process Flow Controller DLL No Process Flow Controller DLL name. This name will automatically appear on the File manifest page Singleton Yes If only one instance of the component is allowed in the process flow, the name of the singleton class for this framework should be listed here. Target Types Yes If this component is only valid for specific hardware targets, those targets should be listed here, separated by commas. Otherwise, the target Any should be used. Table 6-1: Component Publisher Main Page Descriptions Important: When any property of an existing component is edited, it is necessary to update the version of that component when it is republished so that the cache properties of the old component are not reused. If the developer chooses not to update the version, it becomes necessary to delete the existing component version in the component cache to ensure the component will reflect the changes made by the newly published component Figure 6-2: Component Publisher Main Page Design, Runtime, and I 2 C Properties Design Properties and Runtime Properties of the Component Publisher are used to add custom properties to a component. The difference between the two is that Runtime Properties of a component 1-32

39 may be edited while a process flow is running on the evaluation module, where as design properties of a component cannot. Note: A value of [-1] indicates that a properties is not runtime editable, whereas a value of [1] indicates that a value is a runtime property. The I 2 C Properties of a component are used to control the I 2 C interface of a component. Each Component requires the following properties. I 2 CAddressN: Integer property containing the I 2 C register number I 2 CLengthN: Hidden, read-only integer property containing the length (in bytes) of the I 2 C data send to this address. DspCoefBlockStartN: If DSP coefficient ram is used to receive the values from I 2 C, and integer property containing the DSP coefficient address. Up to 16 sets of the above property can be defined, permitting a component to use up to 16 I 2 C subaddress. N is an integer from 1 to 16. Note: A Handler Index value of [1] is used for coefficients values, whereas a value of [2] is used for data values Table 6-2 describes the property that can be set in the Design Properties Tab Type Type specification of the property. Click the arrow to select a type. Properties may be one of the following types; - Integer String - Enumerated List of Values Fixed Point Fixed Point - Floating Point Name Instance Number Channel Number Value (All Rates) Description Values List Name of the property If this property is tied to a specific value of the instances property within a component, this value should reflect that instance If this property is tied to a specific value of the Channels Property, this value should be set to that channel, otherwise [-1] Initial value of the property. The specify different values for each sample rate, select the Expand Values Checkbox Brief Description of the property Specify a values list for the property (Type Enum only) 33

40 Minimum Value Maximum Value Minimum Value of Property (Type Int, DapShort, DapLong, and Float only) Maximum Value of Property (Type Int, DapShort, DapLong, and Float only) Table 6-2: Description of Design Properties Figure 6-3: Component Publisher Runtime and I 2 C Properties Component Recepies The PurePath Studio GDE code generation process for a component is specified by defining one or more code generation recipes. The functionality of these recipes allows the component author to have complete control over the code generation process, and provide custom code generators if needed. Table 6-3 shows the recipe options. Figure 6-4: Component Publisher Recipes Instantiator A program to be used to generate code. The default template expansion program provided with the GDE is named 1-34

41 TemplateInstantiator.exe. Input Template Output File The Name of the code template file for the component One of the output files used by the TAS3xxx Frameworks (DSP_flow.asm, dsp_calc.asm, 8051_i2C.c, or 8051_init.c) Table 6-3: Component Recipe Options Component File Manifest The Component Publisher requires that all files referenced by a published component be specified in the File Manifest Tab. These referenced files include assembly files, intermediate C files, Icon files, DSP assembly code templates, and custom code generators. The File Manifest page is used to create the Component.zip file that is used by PurePath Studio Graphical Development Environment. Figure 6-5: Component Publisher File Manifest Note: Any files that are entered on the Component Publisher Main page such as.html or DLL files will automatically propagate to the File Manifest Tab, and cannot be deleted Pop-Up Graphical User Interface The Pop-Up GUI interface in the GDE provides a mechanism for building custom Pop-Up GUIs that run within the GDE and configure components through the component properties. Pop-Up GUIs are.net assemblies and can be written in any Microsoft.NET language (Managed C++, C#, or Visual Basic). Information about developing a Pop-Up GUI can be accessed in Appendix A of the TAS3108 Component Development White Paper to registered users of the MSAV Extranet. Details about registration can be found in various TAS3xxx EVM User s Guides Component Help Files A component should define a help file, in HTML format, that describes the purpose, configuration, and use of the components. The name of this help file is specified in the Main tab of the Component Publisher. The format of help files can be found in various components of the GDE, however should 35

42 contain the following sections: Overview, Description, Configurable Properties, Configuration GUI (If applicable), I 2 C Interface, and Usage. Appendix A Developing A Custom Components From An Existing Process Flow The following example can be used as a reference to optimizing the assembly code of a GDE process flow to create a custom component. A.1 Definition Of the Desired Component This example will show how to optimize a very simple Process Flow consisting of two components per audio channel. The desired custom component will sequentially add two 48 bit data constant to the input audio signal. The following figure shows the Process Flow for the desired component. A.2 The DSP Code Overview Figure A-1:Finished Process Flow The DSP application assembly code produced by the GDE for this process flow consists of four separate assembly files. These files can be found within the My Process Flows Folder. dsp_main.asm: The main application file. dsp_flow.asm: DSP flow code that is position sensitive with relation to the data flow dsp_calc.asm: DSP calculation code that is performed at the end of each sample. dsp_links.asm: Assembly directives generated by the GDE to link components together. 1-36

43 By viewing the files generated by the GDE, it can be seen that the dsp_calc.asm file is empty. This indicates that calculations to add the two 48 bit constants are accomplished inline by the dsp_flow.asm file. Figure A-2: DSP_flow.asm File. A.3 Transforming The Process Flow Into A Component A.3.1 Remove Input and Output Componet Assembly Code In order to create a component with definable Input and Output ports, it is necessary to remove the DSP assembly code that represents the TAS3xxx Serial Audio Port (SAP) Input and Output components. This can be accomplished in two ways Delete the DSP Assembly code which corresponds to the TAS3xxx Input/Output Components from the dsp_flow.asm after the code is generated by the GDE. Delete the Input / Output Components in the Process Flow and regenerate the code. Note: If the later method is used, it may be necessary to reload the dsp_flow.asm file in the IDE. A.3.2 Linking Intermediate Data and Registers Linked Components in a Process Flow transfer the audio data to other components by temporarily storing the value of the audio in DSP Data ram. This is accomplished through a store instruction of the upstream component and a load instruction from the downstream component. Additionally, a line of NOPs is required at the end of each component to prevent the code generator from making an illegal read. To fully optimize your code, these temporary loads and stores should be bypassed by storing the values in DSP register B or DSP Register L. Note: This may not be possible for all linked components. 37