Handling errors according to their severity is essential to robust simulators. In the SansGUI API, you can use a message string and the function return value to give simulation users warnings and errors with custom error numbers. If you use C/C++ for development, you can also write error messages to the log file passed to your class functions by SansGUI.
The highest byte (8 bits) of the function return value (of SG_RET_CODE type) is defined by SansGUI to indicate how successful the class function has be executed. If there is any problem encountered inside the class function, the simulator should notify SansGUI about the severity of the problem by setting the proper bit in the return value. For the definitions of these bits, please consult DLL Function Return Values in the DLL Function Prototype section of the SansGUI Reference Manual. Some explanations are given as following:
If everything works fine and no further action is needed before executing the next function, it should return the default SG_R_OK.
If the function is executed fine, but a message needs to be issued to the user before continuing, you can put the message in the cMessage character array and return SG_R_LMSG. The string should be NULL terminated and cannot exceed the limit defined by the SG_STR_LEN macro.
If a less severe error is encountered and you can let the user decide whether or not to carry on the simulation, issue a warning message in cMessage and return SG_R_PAUS.
If a severe error is encountered and you have to stop the simulation programmatically, issue an error message in cMessage and return SG_R_STOP.
If you check the class version numbers in iMajor, iMinor, iPatch, and iBuild but they are not what your simulator expects, use SG_R_VERS as the return code to indicate that it is a severe error.
It is a good practice that you check the SG_OBJ structure schema version number at the beginning of the class functions so that the users will not be able to use the wrong version of SansGUI with your simulator. If the schema versions do not match, return SG_R_SCHM to indicate that it is a severe error.
The SG_R_ERR is used by SansGUI for any exception raised during the execution of the class function. SansGUI will stop the simulation run when this situation occurs. In the code of your class functions, do not use it as a return value.
The rest of the 3 bytes (24 bits) in the class function return code can be used by the simulator to issue specific error or warning numbers. The returned number will be displayed to the user along with the error or warning message in the cMessage character array. The range of the message numbers is from 1 to 2 raised up to the 24th power, or approximately, 16 million. When the class function returns, the return code becomes
SG_R_* | 24 Bit Error Number
If there is no bitwise-OR operator in your programming language, simply use the addition operation instead. If you use this feature, it is recommended that you list the numbers with the messages in the reference manual of your simulator. We suggest you use this feature in conjunction with the on-line documentation capability, described in the Preparing On-Line Documentation section in the previous chapter.
An error message will be displayed in a pop-up message dialog and logged in the Message View in the bottom pane. The cMessage argument passed to the class function is a pre-allocated buffer with SG_STR_LEN characters in length. In fact, SansGUI allocates 1 more than SG_STR_LEN characters and stuffs a NULL character in it to avoid potential buffer overrun. You should prepare the string by copying the error message to this buffer with at most SG_STR_LEN characters. If your string is shorter, make sure that it is terminated by a NULL character.
|
|
SansGUI Modeling and Simulation Environment Version 1.2
Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.