Skip to Main Content Skip to Search
Product Documentation

IDE Automation Interface

Getting Started with IDE Automation Interface

Introducing the IDE Automation Interface Tutorial

Embedded Coder software provides a connection between MATLAB software and a processor in VisualDSP++ software. You can use objects as a mechanism to control and manipulate a signal processing application using the computational power of MATLAB software. This approach can help you while you debug and develop your application. Another possible use for automation is creating MATLAB scripts that verify and test algorithms that run in their final implementation on your production processor.

To get you started using objects for VisualDSP++ software, Embedded Coder software includes an example script vdspautointtutorial.m. As you work through this tutorial, you perform the following tasks that step you through creating and using objects for VisualDSP++ IDE.

  1. Select your session.

  2. Create and query objects to VisualDSP++ IDE.

  3. Use MATLAB software to load files into VisualDSP++ software IDE.

  4. Work with your VisualDSP++ IDE project from MATLAB software.

  5. Close the connections you opened to VisualDSP++ IDE.

You use these tasks in any development work you do with signal processing applications. Thus, the tutorial provided here gives you a working process and best practice for using Embedded Coder software and your signal processing programs to develop programs for a range of Analog Devices processors.

The tutorial covers some methods and functions for Embedded Coder software. The functions listed first do not require an adivdsp object. The methods listed require an existing adivdsp object before you can use the function syntax.

Functions for Working with VisualDSP++ Software.  The following table shows functions that do not require an object.

FunctionDescription
listsessionsReturn information about the boards that VisualDSP++ IDE recognizes as installed on your PC.
adivdspConstruct an object that refers to a VisualDSP++ IDE session. When you construct the object you specify the session by processor.

Methods for Working with adivdsp Objects in VisualDSP++ Software.  The following table presents some of the methods that require an adivdsp object.

MethodsDescription

add

Add a file to a project

address

Return the address and page for an entry in the symbol table in VisualDSP++ IDE

build

Build the project in VisualDSP++ software
cdChange the working folder

display (IDE Object)"

Display the properties of an object that references a VisualDSP++ software session

halt

Terminate execution of a process running on the processor

info

Return information about the object or session

isrunning

Test whether the processor is executing a process

load

Load a built project to the processor

open

Open a file in the project

read

Retrieve data from memory on the processor

reset

Restore the program counter (PC) to the entry point for the current program

run

Execute the program loaded on the processor

save

Save files or projects
visibleSet whether VisualDSP++ IDE window is visible on the desktop while VisualDSP++ IDE is running

write

Write data to memory on the processor

Running VisualDSP++ Software on Your Desktop — Visibility.  When you create an adivdsp object in the tutorial in the next section, Embedded Coder starts VisualDSP++ software in the background.

If VisualDSP++ software is running in the background, it does not appear on your desktop, in your task bar, or on the Applications page in the Task Manager. It does appear as a process, idde.exe, on the Processes tab in Task Manager.

You can make the VisualDSP++ IDE visible with the function visible. The function isvisible returns the status of the IDE—is it visible on your desktop. To close the IDE when it is not visible and MATLAB is not running, use the Processes tab in Windows Task Manager and look for idde.exe.

If an object that refers to VisualDSP++ software exists when you close VisualDSP++ software, the application does not close. Windows software moves it to the background (it becomes invisible). Only after you clear all objects that access VisualDSP++ IDE, or close MATLAB, does closing VisualDSP++ unload the application. You can see if VisualDSP++ IDE is running in the background by checking in the Windows Task Manager. When VisualDSP++ IDE is running, the entry idde.exe appears in the Image Name list on the Processes tab.

Running the Interactive Tutorial

You have the option of running this tutorial from the MATLAB command line or entering the functions as described in the following tutorial sections.

To run the tutorial in MATLAB, click run vdspautointtutorial. This command launches the tutorial in an interactive mode where the tutorial program provides prompts and text descriptions to which you respond to move to the next section. The interactive tutorial covers the same information provided by the following tutorial sections. You can view the tutorial MATLAB file used here by clicking vdspautointtutorial.m.

Selecting Your Session and Processor

Embedded Coder IDE requires that you have at least one session available for VisualDSP++ software. To help you select the session to use for this tutorial, and for any development work, Embedded Coder software provides a command line tool, called listsessions, which prints a list of the available sessions. So that you can use this function in a script, listsessions can return a MATLAB structure that you use when you want your script to select a session in the IDE without your help.

  1. To see a list of the sessions that you can use, enter the following command at the MATLAB prompt:

    session_list  =  listsessions
    

    MATLAB returns a list that shows all the sessions that Embedded Coder IDE recognizes as available in your installation.

    session_list =
    
        'ADSP-21060 ADSP-2106x Simulator'
        'ADSP-21362 ADSP-2136x Simulator'
  2. listsessions has a verbose mode that provides further details about the sessions in a cell array. The array contains structures that describe each session—the target type, the platform, and the processor.

    sessionsinfo = listsessions('verbose');
    
        echo off
         sessionname: 'ADSP-21362 ADSP-2136x Simulator'
          targettype: 'ADSP-2136x Family Simulator'
        platformname: 'ADSP-2136x Simulator'
          processors: 'ADSP-21362'
  3. Use adivdsp to create an object that accesses a session in VisualDSP++ IDE.

    IDE_Obj = adivdsp('sessionname','ADSP-21362 ADSP-2136x Simulator','procnum',0)
    

    Sessionname and procnum are property names that specify the property to set. ADSP-21362 ADSP-2136x Simulator is the session to access, and 0 is the number of the processor to refer to in the session.

    When you use adivdsp, you create an object, in this case IDE_Obj, that refers to the session you specify in sessionname.

Querying Objects for VisualDSP++ IDE

In this tutorial section you create the connection between MATLAB and VisualDSP++ IDE. This connection, or object, is a MATLAB object, which for this session you save as variable IDE_Obj. You use function adivdsp to create objects. When you create objects, adivdsp input arguments let you define other object properties, such as the global time-out. Refer to the adivdsp reference information for more about the input arguments.

Use the generated object IDE_Obj to direct actions to your session processor. In the following tasks, IDE_Obj appears in all function syntax that interact with IDE session and the processor: The object IDE_Obj identifies and refers to a specific session. You need to include the object in any method syntax you use to access and manipulate a project or files in a session in VisualDSP++ IDE.

  1. Create an object that refers to your selected session and processor. Enter the following command at the prompt.

    IDE_Obj = adivdsp('sessionname','ADSP-21362 ADSP-2136x Simulator','procnum',0)
    

    If you watch closely, and your machine is not too fast, you see VisualDSP++ software appear briefly when you call adivdsp. If VisualDSP++ was not running before you created the new object, VisualDSP++ software starts and runs in the background.

    Usually, you need to interact with VisualDSP++ while you develop your application. The function visible, controls the state of VisualDSP++ software on your desktop. visible accepts Boolean inputs that make VisualDSP++ software either visible on your desktop (input to visible ≥ 1) or invisible on your desktop (input to visible  =  0). For this tutorial, you need to interact with the development environment, so use visible to set the IDE visibility to 1.

  2. To make VisualDSP++ IDE show on your desktop, enter the following command at the prompt:

    visible(IDE_Obj,1)
  3. Next, enter display(IDE_Obj) at the prompt to see the status information.

    ADIVDSP Object:
      Session name     : ADSP-21362 ADSP-2136x Simulator
      Processor name   : ADSP-21362
      Processor type   : ADSP-21362
      Processor number : 0
      Default timeout  : 10.00 secs
    

    Embedded Coder software provides methods to read the status of a processor:

    • info — Return a structure of testable session conditions.

    • display — Print information about the session and processor.

    • isrunning — Return the state (running or halted) of the processor.

  4. Type procinfo  =  info(IDE_Obj).

    The IDE_Obj link status information provides data about the hardware, as follows:

    procinfo = 
    
        procname: 'ADSP-21362'
        proctype: 'ADSP-21362'
        revision: ''
  5. Verify that the processor is running by entering

    runstatus = isrunning(IDE_Obj)
    

    MATLAB responds, indicating that the processor is stopped, as follows:

    runstatus  = 
    
         0
    

Loading Files into VisualDSP++ IDE

In this part of the tutorial, you load the executable code for the CPU in the IDE. Embedded Coder software includes a tutorial project file for VisualDSP++ IDE. Through the next commands in the tutorial, you locate the tutorial project file and load it into VisualDSP++ IDE. The open method directs VisualDSP++ software to load a project file or workspace file.

VisualDSP++ software has its own workspace and workspace files that are quite different from MATLAB workspace files and the MATLAB workspace. Remember to monitor both workspaces. The next steps change the working folder to your new writable folder.

  1. Use cd to switch to the writable folder

    prj_dir = cd('C:\vdsp_demo')

    where the name and path to the writable folder is a string, such as C:\vdsp_demo. Replace C:\vdsp_demo with the full path to your folder.

  2. Change your working folder to the new folder by entering the following command:

    cd(IDE_Obj,prj_dir)
  3. Next, use the following command to create a new VisualDSP++ software project named dot_product_c.dpj in the new folder:

    new(IDE_Obj,'debug_demo.dpj')

    Look in the IDE to verify that your new project exists. Next you need to add source files to your project.

  4. Add the provided source file—scalarprod.c to the project debug_demo.dpj using the following command:

    add(IDE_Obj, [matlabroot '\toolbox\vdsplink\vdspdemos\src\scalarprod.c'])
    

    The variable matlabroot indicates the root folder of your MATLAB installation. Replace matlabroot with the path to MATLAB on your machine. For more information about the MATLAB root folder, refer to matlabroot in the MATLAB documentation.

  5. Open the file in the IDE from MATLAB by issuing the following command to open the file:

    open(IDE_Obj,[matlabroot '\toolbox\vdsplink\vdspdemos\src\scalarprod.c'])
    

    Switch to the IDE to verify that the files are in your project and open.

  6. Save your project.

    save(IDE_Obj,'debug_demo.dpj','project')

    Your IDE project is saved with the name debug_demo.dpj in your writable folder. The input string 'project' specifies that you are saving a project file.

Running the Project

After you create dot_project_c.dpj in the IDE, you can use Embedded Coder functions to create executable code from the project and load the code to the processor.

The next steps in this tutorial build the executable and download and run it on your processor.

  1. Use the following build command to build an executable module from the project dot_product_c.dpj.

    build(IDE_Obj,30) %Optional input argument 30 sets time out period to 30 seconds.

    At the end of the build process, Embedded Coder software returns a value of 1 to indicate that the build succeeded. If the build process returns a 0, the build failed.

    ans  = 
    
         1
    
  2. To load the new executable to the processor, use load with the project file name and the object name. The name of the executable is debug_demo.dxe, and it is stored with the project in your writable folder, in a subfolder named debug.

    load(IDE_Obj,'c:\vdsp_demo\debug\debug_demo.dxe',30);

Embedded Coder software provides methods to control processor execution—run, halt, and reset. To demonstrate these methods, use run to start the program you loaded on the processor, and then use halt to stop the processor.

Try the following methods at the command prompt.

run(IDE_Obj)      % Start the program running on the processor.
halt(IDE_Obj)     % Halt the processor.
reset(IDE_Obj)    % Reset the program counter to start of program.

Working with Global Variables and Memory

After you load your program on the processor, you can access memory locations and variables. You can then read variables either from the program symbol table or directly from addresses in memory. Three methods—address, read, and write, let you get, read, and write to and from your project and processor.

Start by getting the address of the global variable v1 from the debug_demo project symbol table.

  1. Enter the following command to retrieve the address for v1.

    address_v1 = address(IDE_Obj, 'v1')
    
    address_v1  = 
    
          753666           1
  2. Convert the address from decimal format to hexadecimal.

    dec2hex(address_v1(1))
    
    ans  = 
    
    B8002
    

    The address of global data array v1 is 0xB8002, which is stored in type 1 memory on the processor

  3. With the address of v1 saved as address_v1, use read to return the data from that location. To specify the data type and the number of values to read, add the datatype ('int32') and count (32) input arguments.

    value_v1 = read(IDE_Obj, address_v1, 'int32', 32) % Interpret data as 32-bit integers.
    
    value_v1  = 
    
      Columns 1 through 10
    
         -37    -133      31    -104      32      66    -123      19     140     -28
    
      Columns 11 through 20
    
          16      80      -2      83    -243     148      56     163      46      45
    
      Columns 21 through 30
    
        -217     -11    -164      49      -3      99      21     -61     -26     101
    
      Columns 31 through 32
    
        -101    -151
  4. Repeat the read process for another global variable in the project—v2. Nest the address method inside the read method to reduce typing.

    value_v2 = read(IDE_Obj,address(IDE_Obj,'v2'),'int32',32) 
    
    value_v2  = 
    
      Columns 1 through 10
    
         -50       5     -17      28       5      31     -23    -156       68      -5
    
      Columns 11 through 20
    
        -220       5     -14      57     214     183     213      40     175     144
    
      Columns 21 through 30
    
         -12     -77     -18      77     130     -39     132     107      52     -59
    
      Columns 31 through 32
    
         127     -117

Working with Local Variables and Memory

If you examine the source files for debug_demo in the IDE, you can verify the values for v1 and v2 in the source file scalarprod.c. You can also use the address method to get the addresses of local variables on the stack, after the variable is in scope.

To get the variables in scope (on the stack), you run the program. Adding a breakpoint to the program allows you to read the stack contents when the program stops at the breakpoint. Without the breakpoint, the program runs to completion, and you cannot read the contents of the stack because it no longer exists.

Begin the process by adding a breakpoint to the project file scalarprod.c:

  1. Insert a breakpoint on line 100 of program scalarprod.c with the following command:

    insert(IDE_Obj, 'scalarprod.c', 100)
  2. Run the program to add the variable to the stack, and move the program counter to the breakpoint. Add the optional input argument timeout sets the time out value to 30s instead of the default 20s value:

    run(IDE_Obj,'runtohalt',30)
    

    The program stops at the breakpoint on line 100.

  3. Read the address of the local variable result, and convert it to its hexadecimal equivalent value.

    address_result = address(IDE_Obj,'result','local')
    
    address_result  = 
    
          933884           1
    
    dec2hex(address_result(1))
    
    ans  = 
    
    E3FFC

    address returns 933884 as the location of result in memory, in type 1 memory on the processor, stored in the MATLAB variable address_result.

  4. Use the variable address_result to get the value stored at that address by issuing the following read command:

    actual_value_result = read(IDE_Obj, address_result, 'int32')
    
    actual_value_result  = 
    
           18875

    Verify in the IDE Output Window that 18875 is the accurate value for the dot product.

  5. Use the following command to remove the breakpoint set on line 100.

    remove(IDE_Obj, 'scalarprod.c', 100)

MATLAB includes a dot product function to use to verify the value in actual_value_result. Called dot, the function calculates the dot product of two input vectors. In this case, the inputs are vectors value_v1 and value_v2.

Comparing the two results—expected_value_result in MATLAB with actual_value_result from the processor implementation validates your simulation and implementation. With IDE Automation Interface methods, you can create MATLAB file scripts to test and verify algorithms in their implementation on a processor.

  1. Calculate the expected result by performing the dot function with two input vectors.

    expected_value_result = dot(value_v1, value_v2)
    
    expected_value_result  = 
    
           18875
  2. Test to see if the actual and expected results match.

    isequal(expected_value_result, actual_value_result)
    
    ans  = 
    
         1
  3. After verifying the result and removing the breakpoint, run the program to completion, and then halt and reset the processor.

    run(IDE_Obj)
    halt(IDE_Obj)
    reset(IDE_Obj)

Closing Files and Projects

You can close files in your projects from the MATLAB command line. The method close works at the command line to close programs or projects in the IDE through the adivdsp object and input keywords that describe the kind of file to close.

To finish this tutorial, close the open documents or files in the IDE, and then close the project debug_demo.dpj.

  1. Close all of the open files and documents in the IDE. All of the open files are text files, so use the text input argument.

    close(IDE_Obj, 'all', 'text')
  2. Now, close the project.

    close(IDE_Obj, 'debug_demo.dpj', 'project')

If you close the VisualDSP++ IDE manually outside of MATLAB, clear the IDE handle object in MATLAB. For example, at the MATLAB command line enter:

clear IDE_Obj

Closing the Connections or Cleaning Up VisualDSP++ Software

Objects that you create in Embedded Coder software have connections to VisualDSP++ software. Until you delete these handles, the VisualDSP++ process (idde.exe in the Windows Task Manager) remains in memory. Closing MATLAB removes these objects automatically, but there may be times when it helps to delete the handles manually, without quitting MATLAB.

  1. Use the following command to make the IDE invisible if it is visible on your desktop.

    visible(IDE_Obj.0)
    
  2. To delete your connection to VisualDSP++ IDE, use clear IDE_Obj.

Tutorial Summary

During the tutorial you performed the following tasks:

  1. Selected your session.

  2. Created and queried objects that refer to a session in Embedded Coder to get information about the session and processor.

  3. Used MATLAB to load files into VisualDSP++ IDE, and used methods in MATLAB to run that file.

  4. Accessed variables in the program symbol table and on the processor.

  5. Used the IDE Automation Interface methods to compare the results of a simulation in MATLAB with the same algorithm running on a processor.

  6. Closed the files, projects, and connections you opened to VisualDSP++ IDE.

Constructing Objects

When you create a connection to a session in VisualDSP++ software using the adivdsp function, you create an object. The object implementation relies on MATLAB object-oriented programming capabilities similar to the objects you find in MATLAB or Filter Design Toolbox.

The discussions in this section apply to the objects in Embedded Coder software. Because adivdsp objects use the MATLAB programming techniques, the information about working with the objects, such as how you get or set properties, or use methods, apply to the objects you create in Embedded Coder software.

Like other MATLAB structures, objects in Embedded Coder software have predefined fields referred to as object properties.

You specify object property values by one of the following methods:

For examples of setting link properties, refer to "Setting Property Values with set."

Example — Constructor for adivdsp Objects

The easiest way to create an object is to use the function adivdsp to create an object with the default properties. Create an object named IDE_Obj referring to a session in VisualDSP++ software by entering the following syntax:

IDE_Obj = adivdsp

MATLAB responds with a list of the properties of the object IDE_Obj you created along with the associated default property values.

ADIVDSP Object:
  Session name     : ADSP-21362 ADSP-2136x Simulator
  Processor name   : ADSP-21362
  Processor type   : ADSP-21362
  Processor number : 0
  Default timeout  : 10.00 secs

The object properties are described in the adivdsp documentation.

Properties and Property Values

Objects in this software have properties associated with them. Each property is assigned a value. You can set the values of most properties, either when you create the link or by changing the property value later. However, some properties have read-only values. Also, a few property values, such as the board number and the processor to which the link attaches, become read-only after you create the object. You cannot change those after you create your link.

Setting and Retrieving Property Values

You can set adivdsp object property values by either of the following methods:

Retrieve Embedded Coder software object property values with the get function.

Direct property referencing lets you either set or retrieve property values for adivdsp objects.

Setting Property Values Directly at Construction

To set property values directly when you construct an object, include the following entries in the input argument list for the constructor method adivdsp:

Include as many property names in the argument list for the object construction command as there are properties to set directly.

Example — Setting Object Property Values at Construction.  Suppose that you want to create a link to a session in VisualDSP++ software and set the following object properties:

Set these properties by entering

IDE_Obj = adivdsp('sessionname','ADSP-21060 ADSP-2106x Simulator','procnum',0,'timeout',5);

The sessionname, procnum, and timeout properties are described in Link Properties, as are the other properties for links.

Setting Property Values with set

After you construct an object, the set function lets you modify its property values.

Using the set function, you can change the value of any writable property of an object.

Example — Setting Object Property Values Using set.  To set the time-out specification for the link IDE_Obj from the previous section, enter the following syntax:

set(IDE_Obj,'timeout',8);

get(IDE_Obj,'timeout');
ans = 

     8

The display reflects the changes in the property values.

Retrieving Properties with get

You can use the get command to retrieve the value of an object property.

Example — Retrieving Object Property Values Using get.  To retrieve the value of the sessionname property for vd2, and assign it to a variable, enter the following syntax:

session = get(vd2,'sessionname')

session = 

ADSP-21060 ADSP-2106x Simulator

Direct Property Referencing to Set and Get Values

You can directly set or get property values using MATLAB structure-like referencing. Do this by using a period to access an object property by name, as shown in the following example.

Example — Direct Property Referencing in Links.  To reference an object property value directly, perform the following steps:

  1. Create a link with default values.

  2. Change its time-out and number of open channels.

    IDE_Obj = adivdsp;
    IDE_Obj.time = 6;
    

Overloaded Functions for adivdsp Objects

Several methods and functions in Embedded Coder software have the same name as functions in other MathWorks products. These functions behave similarly to their original counterparts, but you apply them to an object. This concept of having functions with the same name operate on different types of objects (or on data) is called overloading of functions.

For example, the set command is overloaded for objects. After you specify your object by assigning values to its properties, you can apply the methods in this toolbox (such as address for reading an address in memory) directly to the variable name you assign to your object. You do not have to specify your object parameters again.

For a complete list of the methods that act on adivdsp objects, refer to Analog Devices VisualDSP++ in the function reference pages.

adivdsp Object Properties

Embedded Coder software provides links to your processor hardware so you can communicate with processors for which you are developing systems and algorithms. Because Embedded Coder software uses objects to create the links, the parameters you set are called properties and you treat them as properties when you set them, retrieve them, or modify them.

This section details the properties for the objects for VisualDSP++ software. First the section provides tables of the properties, for quick reference. Following the tables, the section offers in-depth descriptions of each property, its name and use, and whether you can set and get the property value associated with the property. Descriptions include a few examples of the property in use.

MATLAB users may find much of this handling of objects familiar. Objects in Embedded Coder software behave like objects in MATLAB and the other object-oriented toolbox products. C++ programmers may already understand the concepts described in this section.

Quick Reference to adivdsp Properties

The following table lists the properties for the links in Embedded Coder software. The second column indicates the object to which the property belongs. Knowing which property belongs to each object tells you how to access the property.

Property NameUser Settable?Description
sessionname

At construction only

Reports the name of the session in VisualDSP++ IDE that the object references.

procnum

At construction only

Stores the number of the processor in the session. If you have more than one processor, this number identifies the specific processor.

timeout

Yes/default

Contains the global time-out setting for the link.

Some properties are read only. Thus, you cannot set the property value. Other properties you can change at any time. If the entry in the User Settable column is "At construction only", you can set the property value only when you create the object. Thereafter it is read only.

Details About adivdsp Object Properties

To use the objects for VisualDSP++ interface, set values for the following:

Details of the properties associated with adivdsp objects appear in the following sections, listed in alphabetical order by property name.

procnum.  Property procnum identifies the processor referenced by an object for Embedded Coder IDE. Use procnum to specify the processor you are working with in the session specified by sessionname. The VisualDSP++ Configurator assigns a number to each processor installed in each session. To determine the value of procnum for a processor, use listsessions or the Configurator.

To identify a processor, you need the sessionname and procnum values. For sessions with one processor, procnum equals 0. VisualDSP++ IDE numbers the processors on multiprocessor boards sequentially from 0 to the total number of processors. For example, on a board with four processors, the processors are numbered 0, 1, 2, and 3.

The adivdsp object only supports connecting to processor 0.

sessionname.  Property sessionname identifies the session referenced by a Embedded Coder software. When you create an object, you use sessionname to specify the session you are intending to interact with. To get the value for sessionname, use listsessions or the Analog Devices VisualDSP++ Configurator. The Configurator utility assigns the name for each session available on your system.

timeout.  Property timeout specifies how long VisualDSP++ software waits for any process to finish. You set the global time-out when you create an object for a session in VisualDSP++ IDE. The default global time-out value 10 s. The following example shows the timeout value for object vd2.

display(vd2)

ADIVDSP Object:
  Session name     : ADSP-21060 ADSP-2106x Simulator
  Processor name   : ADSP-21060
  Processor type   : ADSP-21060
  Processor number : 0
  Default timeout  : 10.00 secs
  


Related Products & Applications

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

 © 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS