IDE Automation Interface

Getting Started with IDE Automation Interface

• Introducing the IDE Automation Interface Tutorial

• Starting and Stopping Green Hills MULTI From the MATLAB Desktop

• Running the Interactive Tutorial

• Querying Objects for Green Hills MULTI Software

• Loading Files into Green Hills MULTI Software

• Running the Project

• Working With Data in Memory

• More Memory Data Manipulation

• Closing the Connections to Green Hills MULTI Software

• Tasks Performed During the Tutorial

Introducing the IDE Automation Interface Tutorial

Embedded Coder software provides a connection between MATLAB software and a processor in Green Hills MULTI development environment. You use MATLAB 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 designate a server and processor in Green Hills MULTI software. The object you create is specific to the server and processor you specify.

To help you start using objects in the software, Embedded Coder software includes a tutorial—multilinkautointtutorial.m. As you work through this tutorial, you perform the following tasks that step you through creating and using objects to interact with the Green Hills MULTI IDE:

1. Select your primary server and port.

2. Create and query objects to Green Hills MULTI IDE.

3. Use MATLAB to load files into Green Hills MULTI IDE.

4. Work with your Green Hills MULTI IDE project from MATLAB.

5. Close the connections you opened to Green Hills MULTI IDE.

The tutorial covers some methods and functions for the software. The following tables show functions and methods for the software. The functions do not require an object. The methods require an existing ghsmulti object to use as an input argument for the method.

Functions for Working with Green Hills MULTI.  The following table shows functions that do not require an object.

Methods for Working with ghsmulti Objects in Green Hills MULTI.  The following table presents some of the methods that require a ghsmulti object.

Starting and Stopping Green Hills MULTI From the MATLAB Desktop

Embedded Coder software provides you the ability to control MULTI software from the MATLAB command window. When you create a ghsmulti object, MATLAB starts the services shown in the following table to enable MATLAB to communicate with the Green Hills MULTI IDE:

Each time you create a ghsmulti object, the software starts another set of the python services shown in the table.

Starting Green Hills MULTI From MATLAB.  When you use the ghsmulti function, the software starts two classes of services—python services and the IDE Link service for each new port. The entries in the following table describe how the software controls the IDE when you create a ghsmulti object:

id=ghsmulti

id=ghsmulti('hostname','localhost','portnum',4444)

id2=ghsmulti

id2=ghsmulti('hostname','localhost','portnum',4446)

When the software starts the IDE Link service, it displays a dialog that includes the following details:

Hostname — the name of the host. For example, localhost

Port Num — the port number. For example, 4444

#Clients — the number of clients. For example, 1

MultiDir — the location of the multi installation. For example, C:\ghs5_01

To open the MULTI Launcher utility, click the Launcher button in the service dialog.

Stopping Green Hills MULTI From MATLAB.  After you complete your development work with the software, best practice suggests that you close the IDE from MATLAB. Two conditions control how you close the IDE, as shown in the following table:

Note   Clicking the task bar icon for the service and selecting close does not close the IDE.

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 multilinkautointtutorial. 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 multilinkautointtutorial.m.

Querying Objects for Green Hills MULTI Software

In this tutorial section you create the connection between MATLAB and Green Hills MULTI IDE. This connection, or ghsmulti object, is a MATLAB object that you save as variable id. You use function ghsmulti to create ghsmulti objects. ghsmulti supports input arguments that let you specify values for ghsmulti object properties, such as the global timeout. Refer to the ghsmulti reference information for more about the input arguments.

Use the generated object id to direct actions to your project and processor. In the following tasks, id appears in all method syntax that interact with the IDE primary target and the processor: The object id identifies and refers to a specific instance of the IDE.

You must include the object in any method syntax you use to access and manipulate a project or files in a session in Green Hills MULTI software:

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

   id = ghsmulti('hostname','localhost','portnum',4444)
   

2. Next, enter display(id) at the prompt to see the status information.

   MULTI Object:
     Host Name        : localhost
     Port Num         : 4444
     Default timeout  : 10.00 secs
     MULTI Dir        : C:\ghs\multi500\ppc\

   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.

3. Verify that the processor is running by entering

   runstatus = isrunning(id)
   

   The MATLAB prompt responds with message that indicates the processor is stopped:

   runstatus =
   
        0
   

Loading Files into Green Hills MULTI Software

You have established the connection to a processor and board and have created and queried objects. Next, give the processor something to do.

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 Green Hills MULTI. Through the next commands in the tutorial, you locate the tutorial project file and load it into Green Hills MULTI. The open method directs Green Hills MULTI 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. Create one in the Microsoft Windows folder structure before you proceed with the this tutorial.

Green Hills MULTI has its own workspace and workspace files that are quite different from MATLAB workspace files and the MATLAB workspace. Remember to monitor both workspaces. To change the working folder to your writable folder:

1. Use cd to switch to the writable folder

   prj_dir=cd('C:\ide_link_mu_demo')

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

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

   cd(id,prj_dir)

3. Use the following command to create a new Green Hills MULTI project named debug_demo.gpj in the new folder:

   new(id,'debug_demo.gpj')

   Switch to the IDE to verify that your new project exists. Next, add source files to your project.

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

   add(id,'multilinkautointtutorial.c')
   

5. Save your project.

   save(id,'my_debug_demo.gpj','project')

   Your IDE project is saved with the name my_debug_demo.gpj in your writable folder. The input string, project, specifies that you are saving a project file.

6. Next, set the build options for your project. Use the following command to set the compiler build options to use and specify a processor (optional).

   setbuildopt(id,'Compiler','-G -cpu=V850')

   The input argument -cpu=V850 is optional to specify the processor.

Running the Project

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

To 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 debug_demo.gpj.

   build(id,'all',20) % Set optional time-out period to 20 seconds.

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.

   load(id,'debug_demo',30); % Set time-out value to 30 seconds.

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

1. Enter the following methods at the command prompt and review the response in the MATLAB command window.

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

   Use isrunning after the run method to verify that the processor is running. After you stop the processor, isrunning can verify that the processor has stopped.

Working With Data in Memory

Embedded Coder software provides methods that enable you to read and write data to memory on the processor. Reading and writing data depends on the symbol table for your project. The symbol table is available only after you load the executable into the debugger. This sections introduces address and dec2hex. Use them to read the addresses of two global variables—ddat and idat.

1. After you load debug_demo into the debugger, enter the following commands to read the addresses of ddat and idat:

   ddatA=address(id,'ddat')
   ddatA =
        3145744        0
   
   ddatI=address(id,'idat')
   
   ddatI =
   
        3145728           0
   

2. Review the results in hexadecimal representation.

   dec2hex(ddatA)
   
   ans =
   
   300010
   000000
   
   dec2hex(ddatI)
   
   ans =
   
   300000
   000000

After you load the target code to the processor, you can examine and modify data values in memory, as the previous read function examples demonstrated.

For non-changing data values in memory (static values), the values are available immediately after you load the program file.

A more interesting case is looking at variable values that change during program execution. Manipulating changing data values at intermediate points during execution can provide helpful analysis and verification information.

To enable you to read and write data while your program is running, the software provides methods to insert and delete breakpoints in the source programs. Inserting breakpoints lets you pause program execution to read or change variable data values. You cannot change values while your program is running.

The method insert creates a new breakpoint at either a source file locations, such as a line number, or at a physical memory address. insert takes either the line number or the address as an input argument.

To read the values in the next section of this tutorial, use the following methods to insert breakpoints at lines 24 and 29 in the source file multilinkautointtutorial.c

1. Change folders to your original working folder.

   cd(id,proj_dir);

2. (Optional for convenience) Create variables for the line numbers in the source file.

   brkpt24 = 24;
   brtpt29 = 29;

3. Use the following commands to insert breakpoints on line 24 and line 29 of the source file:

   insert(id,'multilinkautointtutorial',brkpt24); % Insert breakpoint on line 24.
   insert(id,'multilinkautointtutorial',brkpt29); % Insert breakpoint on line 29.

4. Open and activate the file in the IDE from the MATLAB command window by issuing the following commands:

   open(id,'multilinkautointtutorial');
   activate(id,'multilinkautointtutorial');
   

   Activating multilinkautointtutorial.c transfers focus in the IDE to the activated file. Switch to the IDE to verify that the file is in your project and open.

When you look in the IDE debugger window, the breakpoints you added to multilinkautointtutorial.c are marked by a STOP sign icon on lines 24 and 29.

A similar method, remove, deletes breakpoints.

To help you inspect the source file in the IDE and verify the breakpoints, the open and activate methods display the file multilinkautointtutorial.c in the IDE and force the source file to the front.

One final method actually connects the IDE to your hardware or simulator. connect takes a ghsmulti object as an input argument to connect the specific IDE primary target referenced by id to the associated processor.

More Memory Data Manipulation

The source file multilinkaautointtutorial.c defines two 1-by-4 global data arrays—ddat and idat. You can locate the declaration in the file. Embedded Coder software provides the read and write methods so you can access the arrays from MATLAB. Find the declaration and note the initialization values.

This tutorial section demonstrates reading and writing data in memory, and controlling the processor.

1. Get the address of the symbols ddat and idat. Enter the following commands at the prompt.

   ddat_addr=address(id,'ddat'); % Get address from symbol table.
   idat_addr=address(id,'idat');

2. Create two MATLAB variables to specify the data types for ddat and idat.

   ddat_type-'double';
   idat_type='int32';

3. Declare some values in two MATLAB variables.

   ddat_value=double([pi 12.3 exp(-1) sin(pi/4)]);
   idat_value=int32(1:4);

4. Stop the processor.

   halt(id)

5. Reload the project. If you did not save the source file in the project, reloading the project removes the breakpoints you added and move the program counter (PC) to the start of the program.

   % Reload program file (.gpj). Reset PC to program start.
   reload(id,100);

6. Use the following commands to restore the breakpoints on line 24 and 29.

   insert(id,'multilinkautointtutorial.c',brkpt24);
   insert(id,'multilinkautointtutorial.c',brkpt29);

7. Use the following method to connect the IDE to the processor:

   connect(id);

8. With the breakpoints in the code, run the program until it stops at the first breakpoint on line 24.

   run(id,'runtohalt',30); % Set time-out to 30 seconds.

9. Check the current values stored in ddat and idat. Later in this tutorial you change these values from MATLAB.

   % Do ddat values match initialization values in the source?
   ddatV=read(id,address(id,'ddat',ddat_type,4) 
   idatV=read(id,address(id,'idat',idat_type,4)

   MATLAB displays the values of ddatV and idatV.

   ddatV=
   
      16.300   -2.1300   5.1000   11.8000
   
   idatV=
   
           1 508   646   7000

10. Change the values in ddat and idat by writing new values to the memory addresses.

    % Write pi, 12.3, exp(-1), and .7070 to memory.
    write(id,address(id,'ddata'),ddat_value) 
    % Write vector [1:4] to memory.
    write(id,address(id,'idat'),idat_value) 

11. Resume the program execution from the breakpoint and run until the program stops.

    run(id,'runtohalt','30); % Stop at next breakpoint (line 29).

12. Read the values in memory for ddat and idat to verify the changes.

    % Read the data as double data type.
    ddatV = read(id,address(id(id,'ddat'),ddat_type,4) 
    
    ddatV=
    
    3.1416   12.3000   0.3679   0.7071
    
    % Read the data as int32 data type.
    idatV = read(id,address(id,'idat'),idat_type,4) 
    
    idatV=
    
           1   2   3   4

    The data stored in ddat and idat are what you wrote to memory.

13. After you review the data, restart the processor to run to return the PC to the program start.

    restart(id);

Closing the Connections to Green Hills MULTI Software

Objects that you create in Embedded Coder software have connections to Green Hills MULTI IDE. Until you delete these objects, the Green Hills MULTI 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 ghsmulti object, the software does not close the running IDE Link service. When it does close the IDE, it 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 your projects and files before you clear ghsmulti objects from your MATLAB workspace.

Use the following commands to close the project files in Green Hills MULTI IDE and remove the breakpoints you added to the source file.

close(id,'debug_demo.gpj','project') % Close the project file.
remove(id,'multilinkautointtutorial.c',brkpt24);

remove(id,'multilinkautointtutorial.c',brkpt29);

Finally, to delete your link to Green Hills MULTI use clear id.

You have completed the IDE Automation Interface tutorial using Embedded Coder software.

Tasks Performed During the Tutorial

During the tutorial you performed the following tasks:

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

2. Used MATLAB software to load files into the Green Hills MULTI IDE and used methods in MATLAB software to run that file.

3. Closed the links you opened to Green Hills MULTI software.

This set of tasks is used in any development work you do with signal processing applications. Thus, the tutorial gives you a working process for using Embedded Coder software and your signal processing programs to develop programs for a range of processors.

Back to Top

Constructing Objects

When you create a connection to a session in Green Hills MULTI using the ghsmulti function, you create a ghsmulti object (in object-oriented design terms, you instantiate the ghsmulti object). The object implementation relies on MATLAB object-oriented programming capabilities like the objects in MATLAB or DSP System Toolbox software.

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

Like other MATLAB structures, ghsmulti objects have predefined fields referred to as object properties.

You specify object property values by 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".

Example — Constructor for ghsmulti Objects

The easiest way to create an object is to use the function ghsmulti to create an object with the default properties. Create an object named id referring to a session in Green Hills MULTI by entering the following syntax:

id = ghsmulti

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

MULTI Object:
  Host Name        : localhost
  Port Num         : 4444
  Default timeout  : 10.00 secs
  MULTI Dir        : C:\ghs\multi500\ppc\

The object properties are described in the ghsmulti documentation.

Note   These properties are set to default values when you construct links.

Back to Top

Properties and Property Values

• Working with Properties

• Setting and Retrieving Property Values

• Setting Property Values Directly at Construction

• Setting Property Values with set

• Retrieving Properties with get

• Direct Property Referencing to Set and Get Values

• Overloaded Functions for ghsmulti Objects

Working with Properties

Links (or objects) in this Embedded Coder 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 ghsmulti 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 ghsmulti object property values with the get function.

Direct property referencing lets you either set or retrieve property values for ghsmulti 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 ghsmulti:

• 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 property value to associate with the named property. Sometimes this value is also a string.

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

Example — Setting Link Property Values at Construction.  Create a  connection to an instance of the IDE in Green Hills MULTI software and set the following object properties:

• Link to the specified MULTI instance and host.

• Specify the communication port on the host.

• Set the global timeout to 5 s. The default is 10 s.

Set these properties when you construct the object by entering

id = ghsmulti('hostname','localhost','portnum',4444,'timeout',5);

The localhost, portnum, 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 Set link property values.

Example — Setting Link Property Values Using set.  To set the timeout specification for the link id from the previous section, enter the following syntax:

set(id,'timeout',8);

get(id,'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 Link Property Values Using get.  To retrieve the value of the hostnameproperty for id, and assign it to a variable, enter the following syntax:

host=get(id,'hostname')

host =

localhost

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.

   id = ghsmulti;
   id.time = 6;
   

Overloaded Functions for ghsmulti 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 list of the methods that act on ghsmulti objects, refer to the Green Hills MULTI in the function reference pages.

Back to Top

ghsmulti Object Properties

• Quick Reference to ghsmulti Properties

• Details About ghsmulti Object Properties

Quick Reference to ghsmulti Properties

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

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 ghsmulti Object Properties

To use the objects for Green Hills MULTI interface, set values for the following:

• hostname — Specify the session with which the object interacts.

• portnum — Specify the processor in the session. If the board has multiple processors, procnum identifies the processor to use.

• timeout — Specify the global timeout value. (Optional. Default is 10 s.)

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

hostname.  Property hostname identifies the host that is running the IDE Link service. Use hostname to specify the machine to host your service.

To work with a service, you need the hostname and portnum values. Hostname supports the string localhost only.

portnum.  Property portnum specifies the port for communicating with the IDE Link service. MATLAB uses sockets to communicate with Green Hills MULTI. The portnum property value specifies the port, with a default value of 4444. When you create a new ghsmulti object, Embedded Coder software assumes the port value is 4444 unless you enter a different value when you configure the software or use the portnum input argument with ghsmulti.

timeout.  Property timeout specifies how long Green Hills MULTI waits for any process to finish. You set the global timeout when you create an object for a session in Green Hills MULTI. The default global timeout value 10 s. The following example shows the timeout value for object id2.

display(id2)

MULTI Object:
  Host Name        : localhost
  Port Num         : 4444
  Default timeout  : 10.00 secs
  MULTI Dir        : C:\ghs\multi500\ppc\

Back to Top

Getting Started

IDE Project Generator

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

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

Get this Simulink Kit