Debugging DSPLink using SET FAILURE REASON prints

END OF LIFE

DSP Link is still available for download, but no further releases or updates are planned. Please see IPC Software Options for details and alternatives.

Overview

When a DSPLink API call fails with error, the error code provides information about the type and cause of failure.

However, sometimes, even though the error code is known, it is not clear why the failure is occurring. For example, a generic failure code is seen DSP_EFAIL, which may be returned from multiple locations within DSPLink. It is not immediately obvious where the failure lies. In this case, the further level of debugging can be used, by just enabling SET_FAILURE_REASON print.

SET_FAILURE_REASON is a technique used within DSPLink to log failure occurring at any location within the source code. By printing the failure reason, it gives immediate information about the file, line number and failure code, which can be used to understand why the failure has occurred. Since DSPLink source code is available for reference, the reason for failure can be identified in most cases.

Enabling SET_FAILURE_REASON prints on user-side

If TRACE is enabled, in case of any API failure, SET_FAILURE_REASON prints will start coming within the output to the console. For instructions on enabling trace, refer to the Enabling trace in DSPLink article.

Enabling SET_FAILURE_REASON prints on kernel-side

File: ${DSPLINK}/dsplink/gpp/src/gen/trc.c
Function: TRC_SetReason()
Existing Code:
<syntaxhighlight lang='c'>

1. if defined(DDSP_DEBUG)

   TRC_3PRINT (TRC_LEVEL7,
               "Failure [0x%x] in [0x%x] at line %d\n",
               status, FileId, Line) ;

1. endif /* #if defined(DDSP_DEBUG) */

</syntaxhighlight>

Add: <syntaxhighlight lang='c'>

    PRINT_Printf ("Failure [0x%x] in [0x%x] at line %d\n",
                  status, FileId, Line) ;

</syntaxhighlight>

• Now rebuild the GPP-side of DSPLink in debug build.
• Run the application
• Some kernel prints will be seen of the type:

Failure [0x8000800C] in [0x71B] at line 455 

To interpret this:

• Refer to release source code for the interpretation of the numbers in above statement.
• File ${DSPLINK}/gpp/inc/_signature.h has the identifiers for all source files.
• 0x8000800C is the error code. It is DSP_EMEMORY.
• The 0x71B refers to file identifiers. From the _signature.h file, this corresponds to FID_C_LDRV_POOL source file, i.e. ldrv_pool.c.
• The line number is 455 within the ldrv_pool.c file. This indicates that the failure DSP_EMEMORY is due to failure in allocation from shared memory, which means that the amount of shared memory specified for the pool cannot fit into the specified memory entry in the configuration.
• The first SET_FAILURE_REASON print usually indicates the original cause of failure. The subsequent failures usually occur as a result of the first failure.