Error Reporting for XGL Device Pipelines

XGL provides an error-reporting mechanism that is used when an error is detected during the execution of an XGL application. If you want an error to be reported to the application, you must explicitly add code to the device pipeline to handle error conditions.

Error-Handling Mechanism

When XGL detects an error, it calls an internal error handling function. For device-independent error handling, this function assigns values to error attributes, searches an internal look-up table for the error message, and retrieves the appropriate error message string. For device-dependent error handling, the error handling function assigns values to error attributes, searches for the error file that contains localized error messages, and retrieves the appropriate error message string. When the error message string is retrieved, the error handling function calls the application-settable error notification function for further processing of the error.

Error processing is handled centrally in a device-independent manner by the System State object. For maintainability, however, most error-specific attributes and methods are defined in a separate Error class. The System State class defines the API interface functions used for error processing and contains error attributes exposed at the API. The Error class contains the default error notification function, functions that initialize the path to the error file, and a function used for error notification when System State creation fails. The Error class also defines the error attributes for the System State object. Other attributes in the Error class define state information that is saved when an error occurs. These are shown in Table 11-1.

Table 11-1

Information	Description
Type	RECOVERABLE or NON-RECOVERABLE
Category	SYSTEM, CONFIGURATION, RESOURCE, ARITHMETIC, USER
ID	An error number in the form: <pipeline abbrev.>-##
Message	An error message string

Table 11-1

Information	Description
Operator	XGL API operator in use when the error occurred
Object	XGL object in use when the error occurred
Operands	Two operands of error notification

If error checking is on (the application has set XGL_SYS_ST_ERROR_DETECTION to TRUE), XGL will check for a set of error conditions, such as a NULL input point list. For the list of errors, see the XGL Programmer's Guide. Other errors must be handled by the pipeline.

---

Note - The XGL device-independent code is not responsible for some kinds of errors, such as the validity of primitive arguments or errors in input data. The device pipeline can check for these errors and implement error handling for them.

---

Error Message Files

Binary-encoded files containing versions of error message strings are located in:

{path}/{LANG}/LC_MESSAGES/file.mo

where {path} is $XGLHOME/lib/locale if $XGLHOME is set, or /opt/SUNWits/Graphics-sw/xgl/lib/locale if $XGLHOME is not set. {LANG} is en_US for English language messages. Error message files that have been localized to the native language of the user are found in other {LANG} directories. Files named xgl<company abbrev><pipeline abbrev>.mo contain messages for errors that only occur within a specific pipeline.

In order to determine what error messages exist in the error files, English clear-text (ASCII) versions of the files are located in the following directories:

• For device-independent error messages - {path}/include/xgl/xgl_errors_di.po
• For pipeline error message files - {path}/src/<pipeline>/include/xgl_errors_<pipeline>.po

The pipeline *.po files are of the form:

msgid"Key String" (same as the error_id string)
msgstr"Translatable error message string"

The UNIX utility msgfmt encodes the *.po ASCII files to create the *.mo binary-encoded versions, which must be placed in the locale directory described above.

Error Reporting Macros

The recommended way to call the XGL internal error-handling function from within the pipeline code is to use the error-reporting macros XGLI_ERROR and XGLI_DI_ERROR, These macros are defined in the file <xgl_dirs>/src/include/xgli/ErrorMacros.h.

The XGLI_ERROR macro can be used to call the error-reporting function for errors that are defined in the pipeline *.mo files. The interface for XGLI_ERROR is defined:

XGLI_ERROR(sys_state, type, category, error_id, object, op1, op2) XglSysState* sys_state Pointer to current system state; can be NULL; if NULL, then internalfunction will first get system state pointer from global state Xgl_error_type type Error type for the particular error Xgl_error_category category Error category for the error char* error_id Identification string for the error Xgl_obj_type object Object type of currently active object char* op1 Optional operand for this error char* op2 Optional operand for this error

XGLI_DI_ERROR is used to report device-independent errors defined in XGL's internal error look-up table. The interface for XGLI_DI_ERROR is defined as:

XGLI_DI_ERROR(sys_state, error_id, object, op1, op2) XglSysState* sys_state Pointer to current system state; can be NULL; if NULL, then internal function will first get system state pointer from global state char* error_id Identification string for the error Xgl_obj_type object Object type of currently active object char* op1 Optional operand for this error char* op2 Optional operand for this error

The specific error message used by the error-handling function is identified by the error_id parameter passed to these macros. The error_id is a character string of one of the following forms, where ## is the error number specified in either the internal look-up table or the localized error message file:

• di-## - For error messages from the device-independent error look-up table
• <pipeline abbrev>-##- For error messages from pipeline .mo files associated with the originally supported SunSoft/SMCC frame buffers
• xgl<company abbrev><pipeline abbrev>-##- For error messages from independent hardware vendor (IHV) pipeline .mo files

The operand values (op1 and op2) may be used to add useful non-internationalized information (such as numbers or XGL attribute names) to the error report. Other parameters passed to the error macros are self-explanatory. For more information on error types and categories, see the XGL Architecture Guide or the XGL Programmer's Guide.

---

Note - The macros XGLI_ERROR and XGLI_DI_ERROR use the current operator set by the XGL core wrappers during error reporting. A device pipeline should never set the current operator in the pipeline.

---

Example of Error Reporting Using the Error Macros

Suppose you want to check for a malloc error in your pipeline code. The following steps describe how to do this.

1. Search the ASCII clear-text version of the device-independent and pipeline error files for an error message corresponding to the error condition for which you are checking.

   In the case of a malloc error, the following error message is defined in

xgl_errors_di.po:

 msgid   "di-1: malloc or new failed: out of memory"
 msgstr  "di-1: malloc or new failed: out of memory"

Note that the error message format for pipeline error messages is slightly different. See the GX error message file xgl_errors_cg6.po for an example.

2. Add the following #include to your source code module:

    #include "xgli/SysState.h"

3. Add a call to one of the two error-reporting macros where you detect the error in your code.

   The following code fragment shows an example.

   if (!(pts = (Foo *)malloc(bar * sizeof(Foo)))) {
      XGLI_DI_ERROR (system_state, "di-1", XGL_3D_CTX, NULL, NULL);
      return (-1);
   }

If the handle to the System State object is not known, you can call the macro using a NULL value for the System State parameter as shown below:

XGLI_DI_ERROR ((XglSysState *)NULL, "di-1", XGL_3D_CTX,
                 NULL, NULL);

For device-independent errors, the error-handling function searches the internal look-up table for the error message string corresponding to the error_id passed by the user, assigns values to internal error attributes, and calls an error notification function (either the default or one set by the XGL application). The

default error notification function prints an error message to stderr. For example, in the case of the malloc error above, the following message is printed:

Error number di-1: malloc or new failed: out of memory Operator: xgl_polygon Object: XGL_3D_CTX

Creating a Pipeline Error Message File

You can create a new error message file for your pipeline and add error messages to it. Error messages in this file must be specific to the pipeline and should not duplicate error messages that are already available in the device-independent error message file. Follow these steps to create a new error message file.

1. Use the template named xgl_errors_Skeleton.po in SUNWddk/ddk_2.5.1/xgl/src/dd/skeleton/include.

2. Change all occurrences of <company abbrev> and <pipeline abbrev> to correspond to your company abbreviation and pipeline (device) abbreviation.

   For example, in the skeleton template, change SYMBOLskeleton-1 to your company name and abbreviation.

3. Add error messages at the end of the file.

   Two lines are required for each error message: a msgid line and a msgstr line. Examine the xgl_errors_Skeleton.po file for an example.

A clear-text error message .po file is automatically converted to the binary-encoded version when you do make extract. Use the XGLI_ERROR macro described above to call the error handler with the error messages you define in your .po file.