Full Library / System_Language / C_and_CPP / Application_Interface
Block Name: Application_Interface

Code File Location: VisualSim/interfaces/customC/CustomC

Description

The Application_Interface block provisdes an API to integrate executables and C++ code into to use as another block within VisualSim.  Data can be sent from VisualSim blocks to the code via a port and also receive through this API.  The module name must be unique for each code block.  Multiple instances of the same block can exist in the model.

The Application_Interface block is a non-blocking block.  This means that while this block executes the rest of the VisualSim model will also continue to execute.  There are specific C++ functions available that can control transfer schedule using a clock or trigger mechanism within VisualSim.

To learn about this interface, look at the Example System. All the cpp and header files are located in $VS\demo\Interfaces\CustomC\Master_Bus_Slave directory.

  Block Setup

The C++ API works as follows:

Note: Before starting the C++ API, make sure to configure the items listed above for the C++ compiler, Java Home, VS_C_Library (base location of the compiled files), IP address and port_name of the machine where the C++ executable is located.  If using the same machine, then use the defaults. Check the Configure section below for details.

To generate a C++ block, follow this procedure:

Configure

Before using VisualSim Application_Interface block, make sure the following attributes have been set in the $VS/VSconfig.Properties or $VS/VSconfig_linux.Properties and $VS/VisualSim.bat or $VS/VisualSim.sh files:

JAVA_HOME: Make sure the JAVA_HOME variable in VisualSim.sh and VisualSim.bat is set to jdk and not jre.  By default, VisualSim only requires jre.

C++ Compiler:  Current support is Visual Studio 2008/2010/2013 and g++ 4.0 and higher.  This parameter is located in $VS/VSconfig.Properties (Windows) and $VS/VSconfig_linux.Properties(Unix) and the format is VSDIR=C:\\VisualSim\\VS9.0\\VC.  For UNIX, the setting is in $VS/bin/BuildEXE.sh.  The compiler name is given in CC and the path is CCDIR.

VS_C_Library: This is located in the VisualSim.bat (Windows) and VisualSim.sh (Unix).  This is the base directory that is included in the PATH environment variable.  A directory called CustomC must be created within this directory.  All sources must be located in folders within this CustomC directory.  The folder structure inside can have any hierarchy.  When the "Generate Wrapper" is selected from the Menu, each Application_Interface block in the model will have an associated directory under CustomC.  After compiling there is a file called Proxy + module_name.exe with the respective directories containing the executable.

Remote_Address: This is the IP address of the machine executing the application and is located in the $VS/VSconfig.Properties or $VS/VSconfig_linux.Properties.  The main VisualSim can be on one machine and the Application_Interfaces can be on another machine.  The default is 127.0.0.1 which corresponds to the current machine or local host.

Port_Number: This is corresponding Port Number for the IP Address.  The default is 9200 and can be left unchanged, unless there is a conflict at this port.

Required Line in the code

The CPP file must contain the following setup information:

1. Setup of the Proxy

    ProxyCustomC* createProxy() {//Factory method- creates the init and run methods
        return new CustomCMaster();
    }

2. include interface header file for the socket communication:

#include "../CustomCBus/ProxyCustomCBus.h"

where CustomCBus is the directory of the generated files which is the module name and ProxyCustomCBus is the concatenation of Proxy + module name.

In the code, the user can add code to read the parameters, as explained in the parameter section.  The code can also accept data on input ports and write data to output ports.  For more details on this look in the Port section.

The block supports initialize (init), pre-fire (prefire), fire and post-fire as methods to link to the simulation.  At the start of the simnulation, init method is invoked and executed.  The block can be triggered by data arriving on any of the input ports.  When this occurs the block sends the data to the code.  If there code has any actions for the data, it can be performed.  The pre-fire part of the code can check for dependency or whether all the required data are available.  The fire method is where the execution occurs.  The post-fire method determines if any follow up action needs to occur. This is the recommended use of these methods.  The user is free to use these methods in any way they feel fit.

The data arriving on the inport ports can be buffered as shown in the example.  The input data is used only when the block receives a specific value on the clk input port.  These approaches can be used to schedule the data and the processing. 

The output can be scheduled as required.  Every input does not require an input.  Also, an input is not required for the output.

Block Parameters

The user can add parameters to the block and can access the value of these parameter from the code.  To add a new parameter to a CustomC, double-click on the block and select Add.  Provide a name and initial value.  The parameter can be modified before the start of each simulation.  The parameters can be modified from the Grahical Editor or using the Batch Mode Simulation.

The block supports integer, double, boolean and string parameters types.  All parameters are presented as strings to the cpp code. The cpp file must know in advance the parameter name and the type.  C++ conversions must be used to extract the data from the string.  

For example, consider a parameter called num_transactions on the block.  This is of type integer.  The cpp file can access it as follows:

num_transactions = atoi(getParameterValue("Num_Transactions"));

Variants of the atoi function, atol, atof, and atoll (the latter formerly known as atoq), are used to convert a string into a long, float, or long long type,   respectively:

• long atol(const char *str)
• double atof(const char *str)
• long long atoll(const char *str)

Compile

To compile, first select Interface->Generate Wrapper.  This creates the folders for each module and generates all the necessary interfaces files.  Next, select Interface->Compile Wrapper.  This takes the information in bin/BuildEXE to generate a .exe file.  This file is stored in each of the module directory.   

Additional model level parameters are provided for information required by the compiler.  To look at these parameters, right-click on the white space and select Configure.  Build_Files is a parameter that can be added to either the blocks or to the whole model.  This can be used to link other files that are required for the linking.

Block Operation

When the simulation starts the parameter values are available to the block.  The user code determines how to use the parameter values.  

The CustomC block accepts data arriving the input port.  The code inside the module cpp file determines what to do with the arriving data.  The user can accept the data, do processing, wait for additional or sent data on the output port.

Once the Application_Interface block has been configured, the block can be connected up to the full system. Constructor parameters are defined in the CustomC_Module_Name parameters. Currently the CustomC block cannot access custom data types such as enum across the interfaces.  The block supports integers, double/float, strings, General, transactions, booleans and arrays.

Methods have been provided for accessing parameters and read/write to VisualSim data structures.

Once all the Application_Interface blocks have been to compiled and linked, connections and parameter values can be modified for every simulation without recompiling. 

To make a portion of the Application_Interface block to be blocking, add the following to the .h file:
#define START_BLOCKING 47
#define END_BLOCKING 48

Add this to the .ccp file:

    void ClientSWC::startBlocking() {
        sendByte(sockBW, START_BLOCKING);
        receiveByte(sockBW);
    }

    void ClientSWC::endBlocking() {
        sendByte(sockBW, END_BLOCKING);
        receiveByte(sockBW);
    }

Then call this function in the code at the position you want to start the blocking as:

        startBlocking();

Similarly call this functional in the code at the position where you wwant to stop the blocking as:

        endBlocking(); // release blocking while waiting for data
 

CustomC_Module name Vs. Instance name

The CustomC_Module name is listed in the CustomC_Module_Name of the block.  The instance name is the name on top of the Icon and defined by Right-click on the block and selecting Configure Name.

Block Setup

Block has two parameters and the block name must be set:

Custom_C_Module_Name: Name of the module.  This must be unique to each block instance in the model.

Custom_C_File_Path: Path and the cpp file name to the CustomC file location

Customize->Configure Name: Name for this instance of the CustomC_Module.  This must be unique to each block instance in the model.

Port

Input Read

The value on the input ports can be accessed from the external code using the method port_name + "_received"(type value).   The value can be assigned to a local variable.  The data types supported are integer, double, string, boolean, data structures and arrays.  All other advanced data types are sent into a port as a General Data.  Currently, no method has been provided to extract the data type from this General Data.

        void clk_received(int data) {
            phase = data;
        }

Input Write

The data can be sent on a port using the operation "send_" + port_name(value).  

            send_request(data);

Table 1. Types and equivalent Remote Types in VisualSim

Notes

When the Generate Wrapper and Compile Wrapper is selected, it operates on all SystemC, C, CustomC and Verilog blocks in the model.

Make and Compile Parameters

These additional parameters can be a part of the model.  

Include_Search_Path: Add any paths or files to be included in the compile and link process.
Build_Files: These are the cpp files that are required to compile the model.
Struct_Def: This defines the struct for the ports.  Multiple structs can be defined here.  The struct are reference in the Remote Type column of the Port.
Header_Files: The is .h file containing the definition for the above struct.  There can be multiple files included in this line.  The sc_in and sc_out ports can handle data structures on the interface.  This struct defines the fields that are transfered from VisualSim to this port.  This same attribute is also used to list the fields with basic data types for socket port.  These fields are available for mapping to the Generic Payload or use within the SystemC code for any purpose.

When you create these user defined parameters, you need to modify the third line, class to VisualSim.data.expr.StringParameter. This will treat it as a string. When you set it to string, VisualSim treats the data as within “”.

To make the parameter window into text as opposed to line, click on Preferences and select Text by the side of the relevant parameter.

---

 

Created with the Personal Edition of HelpNDoc: Easily create PDF Help documents