XDK API  3.6.0
Documentation
Files | Macros | Typedefs | Enumerations | Functions
Retcode

Return code composition and handling. More...

+ Collaboration diagram for Retcode:

Files

file  BCDS_Retcode.h
 

Macros

#define BCDS_MODULE_ID   0
 
#define BCDS_PACKAGE_ID   0
 
#define RETCODE(Severity, Code)   (RETCODE_COMPOSE((uint32_t)BCDS_PACKAGE_ID, (uint32_t)BCDS_MODULE_ID, (uint32_t)Severity, (uint32_t)Code))
 This macro should be used to compose a Retcode_T value. More...
 
#define RETCODE_COMPOSE(PackageID, ModuleID, Severity, Code)   ( (Retcode_T) ( RETCODE_MK_PACKAGE(PackageID) | RETCODE_MK_MODULEID(ModuleID) | RETCODE_MK_SEVERITY(Severity) | RETOCDE_MK_CODE(Code) ) )
 This Macro composes a return code based on input parameters. More...
 
#define RETCODE_DOPPLE_INITIALIZATION   RETCODE_DOUBLE_INITIALIZATION
 
#define RETCODE_INCONSITENT_STATE   RETCODE_INCONSISTENT_STATE
 
#define RETCODE_INVALID_SEMAPHORE_IN_ISR   RETCODE_INVALID_SIGNAL_IN_ISR
 
#define RETCODE_MK_MODULEID(ModuleID)   ( (ModuleID & 0x000000FFUL) << 16UL )
 A helper macro to make Module Id. More...
 
#define RETCODE_MK_PACKAGE(Package)   ( (Package & 0x000000FFUL) << 24UL )
 A helper macro to make to create the package. More...
 
#define RETCODE_MK_SEVERITY(Severity)   ( (Severity & 0x0000000FUL) << 12UL )
 A helper macro to make severity. More...
 
#define RETCODE_OK   ((Retcode_T) RETCODE_SUCCESS)
 A helper macro to return success. More...
 
#define RETCODE_RTOS_QUEUE_ERROR   RETCODE_QUEUE_ERROR
 
#define RETOCDE_MK_CODE(Code)   (Code & 0x00000FFFUL)
 A helper macro to make code. More...
 

Typedefs

typedef void(* Retcode_ErrorHandlingFunc_T )(Retcode_T error, bool isFromIsr)
 Typedef to represent the Callback function to be called for handling the Error. More...
 
typedef enum Retcode_Severity_E Retcode_Severity_T
 Typedef to represent the Severity of error. More...
 
typedef uint32_t Retcode_T
 This is the return code data type of the BCDS platform. Each retcode is composed of four parts: package, module, severity and code. More...
 

Enumerations

enum  Retcode_General_E
 Enumeration to represent the General return codes. The first codes from 0 to RETCODE_FIRST_CUSTOM_CODE are reserved as general error codes. Packages and projects may define their own codes starting from RETCODE_FIRST_CUSTOM_CODE up to the code 4095. More...
 
enum  Retcode_Severity_E
 Enumeration to represent the Severity of errors. More...
 

Functions

 BCDS_DEPRECATED (Retcode_T Retcode_initialize(Retcode_ErrorHandlingFunc_T func))
 This function initializes the Retcode module. More...
 
 BCDS_DEPRECATED (void Retcode_raiseError(Retcode_T error))
 Raises the error passed as parameter to the error handling function. More...
 
 BCDS_DEPRECATED (static BCDS_INLINE Retcode_Severity_T Retcode_getSeverity(Retcode_T retcode))
 This function provides the Severity of a return code. More...
 
 BCDS_DEPRECATED (static BCDS_INLINE uint32_t Retcode_getCode(Retcode_T retcode))
 This function provides the Error code of a return code. More...
 
static BCDS_INLINE uint32_t Retcode_GetCode (Retcode_T retcode)
 This function provides the Error code of a return code. More...
 
static BCDS_INLINE uint32_t Retcode_getCode (Retcode_T retcode)
 
static BCDS_INLINE uint32_t Retcode_GetModuleId (Retcode_T retcode)
 This function provides the Package of a return code. More...
 
static BCDS_INLINE uint32_t Retcode_GetPackage (Retcode_T retcode)
 This function provides the Package of a return code. More...
 
static BCDS_INLINE uint32_t Retcode_getPackage (Retcode_T retcode)
 
static BCDS_INLINE
Retcode_Severity_T 
Retcode_GetSeverity (Retcode_T retcode)
 This function provides the Severity of a return code. More...
 
static BCDS_INLINE
Retcode_Severity_T 
Retcode_getSeverity (Retcode_T retcode)
 
Retcode_T Retcode_Initialize (Retcode_ErrorHandlingFunc_T func)
 This function initializes the Retcode module. More...
 
void Retcode_RaiseError (Retcode_T error)
 Raises the error passed as parameter to the error handling function. More...
 
void Retcode_RaiseErrorFromIsr (Retcode_T error)
 Raises the error passed as parameter to the error handling function, use from ISR (Interrupt) context only. More...
 

Detailed Description

This module provides helpful functions for creation and handling of return codes. It supports general error codes (see Retcode_General_E), package and module IDs, severity information (see Retcode_Severity_E) and a callback that can be registered to be called whenever a module calls Retcode_RaiseError(Retcode_T).

Macro Definition Documentation

#define BCDS_MODULE_ID   0
#define BCDS_PACKAGE_ID   0
#define RETCODE (   Severity,
  Code 
)    (RETCODE_COMPOSE((uint32_t)BCDS_PACKAGE_ID, (uint32_t)BCDS_MODULE_ID, (uint32_t)Severity, (uint32_t)Code))

This macro creates a Retcode_T from its four parts package, module, severity and code. While severity and code are passed as parameters, the package and module are taken from the macro BCDS_PACKAGE_ID and BCDS_MODULE_ID, which must be defined in each package / module.

Parameters
[in]Severity: Severity of the error, see Retcode_Severity_E
[in]Code: Error code

Example:

1 #define BCDS_PACKAGE_ID 42 // can be defined in makefile of the package, must be unique within global scope
2 #undef BCDS_MODULE_ID
3 #define BCDS_MODULE_ID BCDS_MODULE_ID_MY_MODULE // must be unique within package scope
4 
5 Retcode_T MyFunction(void)
6 {
7  ...
8  return RETCODE(RETCODE_SEVERITY_ERROR, RETCODE_FAILURE);
9 }
#define RETCODE_COMPOSE (   PackageID,
  ModuleID,
  Severity,
  Code 
)    ( (Retcode_T) ( RETCODE_MK_PACKAGE(PackageID) | RETCODE_MK_MODULEID(ModuleID) | RETCODE_MK_SEVERITY(Severity) | RETOCDE_MK_CODE(Code) ) )

This Macro composes a return code based on input parameters.

Parameters
[in]PackageID: Package ID of the corresponding module
[in]ModuleID: Package ID of the corresponding module
[in]Severity: Severity of the error
[in]Code: Error code
Note
Do not use directly, use RETCODE(Severity, Code) instead!
#define RETCODE_DOPPLE_INITIALIZATION   RETCODE_DOUBLE_INITIALIZATION
#define RETCODE_INCONSITENT_STATE   RETCODE_INCONSISTENT_STATE
Deprecated:
The below enums are provided for backward compatibility.
Note
- Interface users are requested to not use this, since it will be removed going forward.
#define RETCODE_INVALID_SEMAPHORE_IN_ISR   RETCODE_INVALID_SIGNAL_IN_ISR
#define RETCODE_MK_MODULEID (   ModuleID)    ( (ModuleID & 0x000000FFUL) << 16UL )
Note
Do not use directly, use RETCODE(Severity, Code) instead!
#define RETCODE_MK_PACKAGE (   Package)    ( (Package & 0x000000FFUL) << 24UL )
Note
Do not use directly, use RETCODE(Severity, Code) instead!
#define RETCODE_MK_SEVERITY (   Severity)    ( (Severity & 0x0000000FUL) << 12UL )
Note
Do not use directly, use RETCODE(Severity, Code) instead!
#define RETCODE_OK   ((Retcode_T) RETCODE_SUCCESS)
#define RETCODE_RTOS_QUEUE_ERROR   RETCODE_QUEUE_ERROR
#define RETOCDE_MK_CODE (   Code)    (Code & 0x00000FFFUL)
Note
Do not use directly, use RETCODE(Severity, Code) instead!

Typedef Documentation

typedef void(* Retcode_ErrorHandlingFunc_T)(Retcode_T error, bool isFromIsr)
Parameters
[in]errorThe error that was raised
[in]isFromIsrTRUE if the error was raised from ISR, FALSE if not
typedef uint32_t Retcode_T

The package (most left byte - 8-bit value) indicates the package where the retcode has been raised.

The module (second left byte - 8-bit value) indicates the module where the retcode has been raised.

The severity (Bits 15 - 12, 4-bit value) indicates the impact of the retcode, i.e. warning, error, fatal error or just an info.

The code (Bits 11 - 0, - 12 bit value) indicates the error code. There are some general error codes defined in Retcode_General_E, ranging from 0 up to RETCODE_FIRST_CUSTOM_CODE. Packages and projects may define their own codes starting from RETCODE_FIRST_CUSTOM_CODE up to the code 4095.

See also
Retcode_Severity_T

Enumeration Type Documentation

Enumerator
RETCODE_SUCCESS 
RETCODE_FAILURE 
RETCODE_OUT_OF_RESOURCES 
RETCODE_INVALID_PARAM 
RETCODE_NOT_SUPPORTED 
RETCODE_INCONSISTENT_STATE 
RETCODE_UNINITIALIZED 
RETCODE_NULL_POINTER 
RETCODE_UNEXPECTED_BEHAVIOR 
RETCODE_DOUBLE_INITIALIZATION 
RETCODE_TIMEOUT 
RETCODE_TIMER_ERROR 
RETCODE_SEMAPHORE_ERROR 
RETCODE_QUEUE_ERROR 
RETCODE_INVALID_SIGNAL_IN_ISR 
RETCODE_FIRST_CUSTOM_CODE 
Enumerator
RETCODE_SEVERITY_NONE 
RETCODE_SEVERITY_FATAL 
RETCODE_SEVERITY_ERROR 
RETCODE_SEVERITY_WARNING 
RETCODE_SEVERITY_INFO 

Function Documentation

BCDS_DEPRECATED ( Retcode_T   Retcode_initializeRetcode_ErrorHandlingFunc_T func)
Deprecated:
since version vxx.xx.xx, replaced by Retcode_Initialize

This function initializes the Retcode module. It registers an error handling callback function. When an error is raised, registered callback function of the corresponding component is called. This function shall be called only once.

Parameters
[in]func: A callback function which is executed when an error is raised.
Return values
RETCODE_OK: On successful init
RETCODE_INCONSITENT_STATE: When this function is called more than once
RETCODE_NULL_POINTER: When the function pointer is NULL
BCDS_DEPRECATED ( void   Retcode_raiseErrorRetcode_T error)

Raises the error passed as parameter to the error handling function, use from ISR (Interrupt) context only.

Deprecated:
since version vxx.xx.xx, replaced by Retcode_RaiseError

Each component may use this function to raise an error to the application if it cannot handle the error itself. This call results in the invocation of the error handling function which has been given while the initialization of the Retcode module using the function Retcode_Initialize().

Parameters
[in]error: The error to be raised to the application
See also
Retcode_Initialize
Retcode_ErrorHandlingFunc_T
Deprecated:
since version vxx.xx.xx, replaced by Retcode_RaiseErrorFromIsr

Each component may use this function to raise an error from ISR to the application. This call results in the invocation of the error handling function with the isFromIsr flag set. As this is called from ISR, the application can define a custom approach (in the registered callback function) based on the isFromIsr flag on how it wants to deal with the error from ISR. i.e. The application can log it into user page, post-process the error and so on, which cannot be done from ISR.

Parameters
[in]error: The error to be raised to the application
See also
Retcode_Initialize
Retcode_ErrorHandlingFunc_T
BCDS_DEPRECATED ( static BCDS_INLINE Retcode_Severity_T   Retcode_getSeverityRetcode_T retcode)

LCOV_EXCL_START : Start of section where code coverage is ignored. Ignore code coverage for the deprecated APIs.

Deprecated:
since version vxx.xx.xx, replaced by Retcode_GetSeverity
Parameters
[in]retcode: return code
Returns
uint32_t : Severity of the error
BCDS_DEPRECATED ( static BCDS_INLINE uint32_t   Retcode_getCodeRetcode_T retcode)

This function provides the Package of a return code.

Deprecated:
since version vxx.xx.xx, replaced by Retcode_GetCode
Parameters
[in]retcode: return code
Returns
uint32_t : Error code
Deprecated:
since version vxx.xx.xx, replaced by Retcode_GetPackage
Parameters
[in]retcode: return code
Returns
uint32_t : Package ID of the corresponding module
static BCDS_INLINE uint32_t Retcode_GetCode ( Retcode_T  retcode)
static
Parameters
[in]retcode: return code
Returns
uint32_t : Error code

+ Here is the caller graph for this function:

static BCDS_INLINE uint32_t Retcode_getCode ( Retcode_T  retcode)
static

+ Here is the call graph for this function:

static BCDS_INLINE uint32_t Retcode_GetModuleId ( Retcode_T  retcode)
static
Parameters
[in]retcode: return code
Returns
uint32_t : Module ID of the corresponding module

+ Here is the caller graph for this function:

static BCDS_INLINE uint32_t Retcode_GetPackage ( Retcode_T  retcode)
static
Parameters
[in]retcode: return code
Returns
uint32_t : Package ID of the corresponding module
static BCDS_INLINE uint32_t Retcode_getPackage ( Retcode_T  retcode)
static

+ Here is the call graph for this function:

static BCDS_INLINE Retcode_Severity_T Retcode_GetSeverity ( Retcode_T  retcode)
static
Parameters
[in]retcode: return code
Returns
uint32_t : Severity of the error

+ Here is the caller graph for this function:

static BCDS_INLINE Retcode_Severity_T Retcode_getSeverity ( Retcode_T  retcode)
static

+ Here is the call graph for this function:

Retcode_T Retcode_Initialize ( Retcode_ErrorHandlingFunc_T  func)

This function initializes the Retcode module. It registers an error handling callback function. When an error is raised, registered callback function of the corresponding component is called. This function shall be called only once.

Parameters
[in]func: A callback function which is executed when an error is raised.
Return values
RETCODE_OK: On successful init
RETCODE_INCONSITENT_STATE: When this function is called more than once
RETCODE_NULL_POINTER: When the function pointer is NULL

+ Here is the caller graph for this function:

void Retcode_RaiseError ( Retcode_T  error)

Each component may use this function to raise an error to the application if it cannot handle the error itself. This call results in the invocation of the error handling function which has been given while the initialization of the Retcode module using the function Retcode_Initialize().

Parameters
[in]error: The error to be raised to the application
See also
Retcode_Initialize
Retcode_ErrorHandlingFunc_T

+ Here is the caller graph for this function:

void Retcode_RaiseErrorFromIsr ( Retcode_T  error)

Each component may use this function to raise an error from ISR to the application. This call results in the invocation of the error handling function with the isFromIsr flag set. As this is called from ISR, the application can define a custom approach (in the registered callback function) based on the isFromIsr flag on how it wants to deal with the error from ISR. i.e. The application can log it into user page, post-process the error and so on, which cannot be done from ISR.

Parameters
[in]error: The error to be raised to the application
See also
Retcode_Initialize
Retcode_ErrorHandlingFunc_T

+ Here is the caller graph for this function:


All rights reserved. The use is subject to the XDK SDK EULA by Bosch Connected Devices and Solutions GmbH.
This documentation file has been automatically generated on Thu Mar 14 2019 19:12:53 by doxygen 1.8.8