Understanding DSPLink error codes

From Texas Instruments Embedded Processors Wiki

Overview

DSPLink returns different error codes for different kinds of failures. Several times, just the error code value returned from the function is sufficient to understand the cause of the failure, and it can be directly corrected.

GPP-side codes

The return values are of two types:

• Success codes: These are positive integers having value 0x8nnn. For example, the common success code DSP_SOK has value 0x8000.
• Failure codes: These are negative integers having value 0x8nnnnnnn. For example, generic failure code DSP_EFAIL has value 0x80008008
• The complete set of return values and their meaning is documented in the error code mapping file errbase.h at ${DSPLINK}/gpp/inc/errbase.h
• The expected return values from each API are documented in the [MODULE].h file. Each [MODULE].h file contains information about all APIs supported by that module, their arguments, return values, entry and leave conditions. For example, proc.h file contains all information about all APIs supported by PROC module. The GPP-side module headers are located in ${DSPLINK}/gpp/inc folder.
• The APIs are also documented in API source reference doxygen generated documentation available with every DSPLink release.

DSP-side status codes

• On DSP-side the return values for DSPLink APIs match DSP/BIOS^TM status codes.
• DSP/BIOS status codes are detailed in DSP/BIOS documentation and within the sys.h DSP/BIOS header file.
• In addition, DSPLink defines its own error codes for RingIO component, starting from the SYS_USER value as supported by DSP/BIOS.
• The expected return values from each API are documented in the [MODULE].h file. Each [MODULE].h file contains information about all APIs supported by that module, their arguments, return values, entry and leave conditions. For example, notify.h file contains all information about all APIs supported by NOTIFY module. The DSP-side module headers are located in ${DSPLINK}/dsp/inc folder.
• MSGQ, SIO and POOL modules are part of DSP/BIOS and are documented within DSP/BIOS user documentation.

Using DSPLink macros for checking error/success status

DSPLink provides macros DSP_SUCCEEDED and DSP_FAILED, which can be used to check whether a DSPLink API call has passed or failed.
These macros should be used for checking return status of all APIs instead of directly checking against status codes. Using these macros ensures that any change in/addition in/removal of return codes shall not impact applications developed using the DSPLink APIs.

Usage

The macros should be used in the following way:

status = MSGQ_open (...) ;
if (DSP_SUCCEEDED (status)) {
    ...
}

Constraints

This macros should not be used as:

if (DSP_SUCCEEDED (MSGQ_open (...))) {
    ...
}

Since DSP_SUCCEEDED is a macro, using it in the above manner can cause the function to be invoked multiple times.