Although the SansGUI Development Environment is not required, you become a developer when you start to override some simulator routines. You will need to consult the SansGUI Reference Manual and the documentation of your specific simulator. In this section, we will discuss the necessary information for implementing overriding routines in DLLs and provide some pointers for your further investigation.
SansGUI uses a unique data type system that contains three sections used in different times:
In model configuration time, when the user prepares the input data and configure the assembly hierarchy for a Project Model, a rich set of GUI Control Types is used. Details can be found in the GUI Control Data Representation section of the SansGUI Reference Manual.
During simulation run time, from the invocation of the simulator to the end of the simulation run, both SansGUI and the simulator use in-memory Object Data Types that can be easily processed by the class functions written in the supported languages. Details can be found in the Object Data Representation section of the SansGUI Reference Manual.
A Data Type Funneling mechanism converts GUI Control Types to Object Data Types for processing. More on this mechanism can be found in the SansGUI Data Type Funneling section of the SansGUI Reference Manual.
You need to be familiar with the data types used in the SansGUI environment and in your particular simulator, especially those used in the classes that you will implement overriding functions.
Two data structures, SG_VALU and SG_OBJ, specify the internal representation of SansGUI Data Objects that is essential to implementing and communicating among class functions and overriding routines. They can be found in the chapter titled SansGUI Data Object Format in the SansGUI Reference Manual.
One great feature in programming the overriding routines for your simulator in the SansGUI environment is that you have only one application programming interface (API) to learn. All the class functions use the same function prototypes with the same set of function arguments and return values. There are different times the class functions will be called, but the function prototype remains the same. For more details, consult the SansGUI Application Programming Interface section in the SansGUI Reference Manual.
Although there is no limitation in how you should break down the overriding functions into different dynamic-linked libraries (DLLs), we recommend that the overriding functions for a class should be contained in a single DLL. Reasons for it is that the overriding functions in different classes share the same set of function names and it is easier to maintain the class functions and keep track of the class attributes of the same class in one DLL module.
A skeleton source file SGover.cpp, located in the inc subdirectory of the SansGUI installation directory, is provided for you as a starting point to create an overriding DLL for a class. It defines all the DLL function entry points in the class. Although you may not implement all the functions, you do not need to remove the unused functions. They just return SG_R_OK by default. What you will need to do in the DLL creation procedure is to open the SGover.cpp file and save it to the source directory where your DLL project is located before inserting your own code to the source file.
You need to configure the Visual C++ interactive development environment (IDE) only once to include SansGUI's inc directory in the include file path. To do so, use Tools>Options... from the pull-down menu. In the Options dialog, click on the Directories tab and in the Show Directories for: field, select Include files. If the inc subdirectory in your SansGUI installation directory is not listed in the Directories, you need to add a new entry and select the inc subdirectory to include it. You can enter the directory path directly or use the Browse button (labeled with ...) to locate it. Click on the OK button to commit the addition.
To create a DLL for the overriding routines in a class, do the following:
Run the Microsoft Visual C++ interactive development environment (IDE).
From the File>New dialog, select the Project tab and then select Win32 Dynamic Link Library. Enter a name for your project and select a directory where the project should reside. Click on the OK button to continue to create a new workspace.
From the Win32 Dynamic Link Library dialog, make sure the default An empty DLL project is selected and then click on the Finish button. A confirmation dialog will pop up. Click on the OK button.
Your Visual C++ IDE will be loaded with the new DLL project. Use File>Open... dialog to locate SGover.cpp in the inc subdirectory of the SansGUI installation directory. You will see the whole set of DLL functions defined in the file.
Use File>Save As... to save the file just opened to the DLL project directory you have just created under a name of your choice. Make sure the name of the new file has a proper file extension (.cpp, for example). This operation effectively copies the skeleton file to a new file under the project directory for your custom coding.
Insert the file into the project. To do so, use Project>Add To Project>Files... to locate and select the new source file. Click on the OK button to insert the file.
Use Build>Set Active Configuration... to select Win32 Release mode. The reason for doing this is that SansGUI has been built with the Release mode. Your DLL code built with the Debug mode without proper modification may conflict with the run-time library used in SansGUI. We will create an optional Win32 Trace mode later for debugging purposes.
Select Project>Settings... to open the Project Settings dialog and then select Win32 Release in the Settings for: field.
Under the C/C++ tab in the Project Settings dialog, select the Code Generation category and make sure that the Use run-time library: field is set to Multithreaded DLL (using the /MD option). Click on the OK button to close the Project Settings dialog.
Select Build>Build <DLL> or press the F7 key to start building the DLL. The <DLL> in the menu is substituted with your project name with a .dll extension.
The DLL should be built successfully. If the compiler cannot find the SGdll.h include file, you need to add the inc subdirectory in the SansGUI installation directory to the include file path. See the Configuring Visual C++ IDE section above for the inclusion of the directory.
The DLL is created under the Release subdirectory of your project directory. Now, you can run SansGUI and specify the overriding DLL path in the Object, or Part Properties dialog. See the previous section on Locating Dynamic-Linked Library.
For debugging your overriding DLL code, a new configuration based upon the Release build can be created and modified to include debug information. We recommend that you create a Win32 Trace configuration as following:
From the Visual C++ IDE with your DLL project loaded, select Build>Configurations... to obtain the Configurations dialog.
Click on the Add... button to obtain the Add Project Configuration dialog.
In the Configuration field, enter Trace to replace Release or Debug.
In the Copy settings from: field, make sure the Win32 Release configuration is selected.
In the Platform field, it should be Win32.
Click on the OK button, a new Win32 Trace configuration should be listed. Click on the Close button to close the Configuration dialog.
Use Project>Settings... to open the Project Settings dialog.
Select Win32 Trace in the Settings for: field.
Under the General tab, you can modify the Intermediate files and Output files directories to be just Trace instead of the long default directory name. This step is optional but recommended. Doing so will allow you to have a better organization of your project subdirectories: Debug, Release, and Trace.
In the General category under the Debug tab, you need to specify the full path of the SansGUI executable (SansGUI.exe in the bin subdirectory of the SansGUI installation directory) in the Executable for debug session: field and the directory where the testing Project Model reside in the Working directory: field.
Under the C/C++ tab, a few changes are needed: 1) in the General category, select Disable (Debug) for Optimization, 2) in the Debug Info: field, select Program Database, and 3) in the Code Generation category, make sure that the Use run-time library: field is set to Multithreaded DLL (using the /MD option).
In the General category under the Link tab, check the Generate debug info option. Leave all other fields with their default settings.
Click on the OK button to close the dialog.
Now you have created a Win32 Trace configuration, select it by using the Build>Set active configuration... menu item.
Build the DLL by Build>Build <DLL> or pressing the F7 key.
If you have other instances of SansGUI environment opened, make sure that they do not have the test Project Model loaded. Now, you can start the debugging session by invoking SansGUI from within the Visual C++ IDE:
Click on the GO button in the Build toolbar or press the F5 key in the IDE.
A dialog appears to state that SansGUI.exe does not contain debug information. Simply click on the OK button to continue. SansGUI will start.
In SansGUI, load your test Project Model.
Open the Properties dialog for the object or part to specify the Trace DLL path. Close the Properties dialog and save the Project Model.
Set a break point in one of your overriding functions in the Visual C++ IDE.
Run the simulation to allow your overriding functions to be called. When the function with the break point is called, the Visual C++ IDE will take over. You can then trace through the code and examine the variables as you would do in other program development.
Similar to C/C++ DLL creation, there is no limitation in how you should break down the overriding functions into different dynamic-linked libraries (DLLs), we recommend that the overriding functions for a class should be contained in a single DLL.
A skeleton source file SGover.f, located in the inc subdirectory of the SansGUI installation directory, is provided for you as a starting point to create an overriding DLL for a class. It defines all the DLL function entry points in the class. Although you may not implement all the functions, you do not need to remove the unused functions. They just return SG_R_OK by default. What you will need to do in the DLL creation procedure is to open the SGover.f file and save it to the source directory where your DLL project is located before inserting your own code to the source file.
You need to configure the interactive development environment (IDE) only once to include SansGUI's inc directory in the include file path. To do so, use Tools>Options... from the pull-down menu. In the Options dialog, click on the Directories tab and in the Show Directories for: field, select Include files. If the inc subdirectory in your SansGUI installation directory is not listed in the Directories, you need to add a new entry and select the inc subdirectory to include it. You can enter the directory path directly or use the Browse button (labeled with ...) to locate it. Click on the OK button to commit the addition.
To create a DLL for the overriding routines in a class, do the following:
Run the Compaq Visual Fortran interactive development environment (IDE).
From the File>New dialog, select the Project tab and then select Fortran Dynamic Link Library. Enter a name for your project and select a directory where the project should reside. Click on the OK button to continue to create a new workspace.
From the Fortran Dynamic Link Library dialog, make sure the default An empty DLL application is selected and then click on the Finish button. A confirmation dialog will pop up. Do not worry about the multithread library being disabled at this moment because we will set it later. Click on the OK button.
Important Step: Your Visual Fortran IDE will be loaded with the new DLL project. Open the Project Settings dialog by using the Project>Settings... menu item. In the Settings for: field, select All Configurations. We need to check the following things in the External Procedures category under the Fortran tab: 1) the External Name Interpretations field should be set to As-is because the function names are case-sensitive. 2) all other fields should use default setting with an asterisk (*) appended, 3) the Append Underscore to External Names field should be cleared, as default. In addition, change the Category selection to Libraries and then select Threaded in the Reentrancy Support: field and Multithreaded DLL in the Use run-time library: field to avoid any potential conflict with the system's library. Click on the OK button to commit the changes.
Use File>Open... dialog to locate SGover.f in the inc subdirectory of the SansGUI installation directory. You will see the whole set of DLL functions defined in the file.
Use File>Save As... to save the file just opened to the DLL project directory you have just created under a name of your choice. Make sure the name of the new file has a proper file extension (.f, for example). This operation effectively copies the skeleton file to a new file under the project directory for your custom coding.
Insert the file into the project. To do so, use Project>Add To Project>Files... to locate and select the new source file. Click on the OK button to insert the file.
Use Build>Set Active Configuration... to select Win32 Release mode. You can also select the Win32 Debug mode to build the DLL later. Either way, the DLL can be used in the SansGUI environment.
Select Build>Build <DLL> or press the F7 key to start building the DLL. The <DLL> in the menu is substituted with your project name with a .dll extension.
The DLL should be built successfully. If the compiler cannot find the SGdllf.h include file, you need to add the inc subdirectory in the SansGUI installation directory in the include file path. See the Configuring Compaq Visual Fortran section above for the inclusion of the directory.
The DLL is created under the Release or Debug subdirectory of your project directory. Now, you can run SansGUI and specify the overriding DLL path in the Object, or Part Properties dialog. See the previous section on Locating Dynamic-Linked Library.
For debugging your overriding DLL code, you will use the Debug build of the DLL.
Open the Project Settings dialog by selecting the Project>Settings... menu item.
In the General category under the Debug tab, you need to specify the full path of the SansGUI executable (SansGUI.exe in the bin subdirectory of the SansGUI installation directory) in the Executable for debug session: field and the directory where the testing Project Model reside in the Working directory: field.
Click on the OK button to close the dialog.
Use the Build>Set active configuration... menu item to select the Win32 Debug mode.
Build the DLL by Build>Build <DLL> or pressing the F7 key.
If you have other instances of SansGUI environment opened, make sure that they do not have the test Project Model loaded. Now, you can start the debugging session by invoking SansGUI from within the Visual Fortran IDE:
Click on the GO button in the Build toolbar or press the F5 key in the IDE.
A dialog appears to state that SansGUI.exe does not contain debug information. Simply click on the OK button to continue. SansGUI will start.
In SansGUI, load your test Project Model.
Open the Properties dialog for the object or part to specify the Debug DLL path. Close the Properties dialog and save the Project Model.
Set a break point in one of your overriding functions in the Visual Fortran IDE.
Run the simulation to allow your overriding functions to be called. When the function with the break point is called, the Visual Fortran IDE will take over. You can then trace through the code and examine the variables as you would do in other program development.
|
|
SansGUI Modeling and Simulation Environment Version 1.2
Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.