| Contents | Index |
| On this page… |
|---|
Getting Started with IDE Automation Interface |
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.
Note Before using the functions available with the objects, you must select a session in the VisualDSP++ IDE. The object you create is specific to a designated session in VisualDSP++ IDE. |
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.
Use MATLAB software to load files into VisualDSP++ software IDE.
Work with your VisualDSP++ IDE project from MATLAB software.
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.
| Function | Description |
|---|---|
| listsessions | Return information about the boards that VisualDSP++ IDE recognizes as installed on your PC. |
| adivdsp | Construct 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.
| Methods | Description |
|---|---|
| Add a file to a project | |
| Return the address and page for an entry in the symbol table in VisualDSP++ IDE | |
| Build the project in VisualDSP++ software | |
| cd | Change the working folder |
| Display the properties of an object that references a VisualDSP++ software session | |
| Terminate execution of a process running on the processor | |
| Return information about the object or session | |
| Test whether the processor is executing a process | |
| Load a built project to the processor | |
| Open a file in the project | |
| Retrieve data from memory on the processor | |
| Restore the program counter (PC) to the entry point for the current program | |
| Execute the program loaded on the processor | |
| Save files or projects | |
| visible | Set whether VisualDSP++ IDE window is visible on the desktop while VisualDSP++ IDE is running |
| 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.
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.
Note To run the interactive tutorial, you must have at least one session configured in VisualDSP++ software. If you do not yet have a session, use the Analog Devices VisualDSP++ Configurator to create a session to use for this tutorial. |
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.
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'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'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.
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.
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.
To make VisualDSP++ IDE show on your desktop, enter the following command at the prompt:
visible(IDE_Obj,1)
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.
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: ''Verify that the processor is running by entering
runstatus = isrunning(IDE_Obj)
MATLAB responds, indicating that the processor is stopped, as follows:
runstatus =
0
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.
Note To continue the tutorial, you must identify or create a folder to which you have write access. Embedded Coder software cannot create a folder for you. If you do not have a writable folder, create one in Windows software before you proceed with the rest of this tutorial. |
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.
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.
Change your working folder to the new folder by entering the following command:
cd(IDE_Obj,prj_dir)
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.
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.
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.
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.
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.
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
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.
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.
Enter the following command to retrieve the address for v1.
address_v1 = address(IDE_Obj, 'v1')
address_v1 =
753666 1Convert 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
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 -151Repeat 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 -117If 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:
Insert a breakpoint on line 100 of program scalarprod.c with the following command:
insert(IDE_Obj, 'scalarprod.c', 100)
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.
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 =
E3FFCaddress returns 933884 as the location of result in memory, in type 1 memory on the processor, stored in the MATLAB variable address_result.
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 =
18875Verify in the IDE Output Window that 18875 is the accurate value for the dot product.
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.
Calculate the expected result by performing the dot function with two input vectors.
expected_value_result = dot(value_v1, value_v2)
expected_value_result =
18875Test to see if the actual and expected results match.
isequal(expected_value_result, actual_value_result)
ans =
1After 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)
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.
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')
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
Note If you have a Project options dialog open, close the Project options dialog before using the close or clear methods. The dialog prevents the methods from working but does not produce an error message. |
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.
Note When you clear the last adivdsp IDE handle object, Embedded Coder software closes VisualDSP++ software. When it closes the IDE, the link software does not save current projects or files in the IDE, and it does not prompt you to save them. A best practice is to save all of your projects and files before you clear adivdsp objects from your MATLAB workspace. |
Use the following command to make the IDE invisible if it is visible on your desktop.
visible(IDE_Obj.0)
To delete your connection to VisualDSP++ IDE, use clear IDE_Obj.
During the tutorial you performed the following tasks:
Created and queried objects that refer to a session in Embedded Coder to get information about the session and processor.
Used MATLAB to load files into VisualDSP++ IDE, and used methods in MATLAB to run that file.
Accessed variables in the program symbol table and on the processor.
Used the IDE Automation Interface methods to compare the results of a simulation in MATLAB with the same algorithm running on a processor.
Closed the files, projects, and connections you opened to VisualDSP++ IDE.
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:
Specifying the property values when you create the object
Creating an object with default property values, and changing some or all of these property values later
For examples of setting link properties, refer to "Setting Property Values with set."
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.
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.
You can set adivdsp object property values by either of the following methods:
Directly when you create the link — see "Setting Property Values Directly at Construction"
By using the set function with an existing link — see "Setting Property Values with set"
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.
To set property values directly when you construct an object, include the following entries in the input argument list for the constructor method adivdsp:
A string for the property name to set followed by a comma. Enclose the string in single quotation marks as you do any string in MATLAB.
The associated property value. Sometimes this value is also a string.
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:
Refer to the specified session.
Connect to the first processor.
Set the global time-out to 5 s. The default is 10 s.
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.
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 =
8The display reflects the changes in the property values.
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
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:
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.
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.
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 Name | User 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.
To use the objects for VisualDSP++ interface, set values for the following:
sessionname — Specify the session with which the object interacts.
procnum — Specify the processor in the session. If the board has multiple processors, procnum identifies the processor to use.
timeout — Specify the global time-out value. (Optional. Default is 10 s.)
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
![]() | Getting Started | IDE Project Generator | ![]() |

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 |