/****************************************************************************** * File name : REPORT.H * Title : INFRA REPORT PACKAGE - Application Interface * Date created : 16 SEP, 1997 * Revision : 2.0 * Author : Zvika Zilberman * * Description : This package provides services for reporting and * debug tracing. The package includes: * - Error coding convention definitions * - Message report interface * - Message filtering interface * - Message distributor interface * - Compatibility with UT_EXCEPTION package * ****************************************************************************** * * History: * 01.05.96 Roie Geron - first cut * 01.09.96 Ilia Maller - start of coding * 21.02.97 Ilia Maller - minor improvements * 16.09.97 Zvika Zilberman - porting to DCME SWINFRA (0200 - 0240) * 29.07.98 Zvika Zilberman - approach to new generation (0300 - 0320) * 10.11.98 Zvika Zilberman - update the new generation (0330) * ****************************************************************************** * Dependencies of SWINFRA packages: * Terminal * Monitor ******************************************************************************/ #ifndef __REPORT_H__ #define __REPORT_H__ /*---------------------------- Includes ---------------------------------------*/ #include "include.h" #include /* _ASSET_STR */ #include "../../Communication/PMR/Common/MessageContainer.pb-c.h" #ifdef __cplusplus extern "C" { #endif /*#define OK 0 #define ERROR -1 //#define FALSE false //#define TRUE true #define OFF 0 #define ON 1 */ #define RET_NOTOK -1 #define RET_OK 0 typedef int STATUS; /*--------------------------- Type definitions -------------------------------*/ /* This following redefinition is the filter level. Reports with lower severity than */ /* the filter's one, won't be sent to the output. */ typedef int ErrorSeverity; #define RpMessage 0x1 #define RpWarning 0x2 #define RpError 0x4 #define RpFatalError 0x8 #define RpPrivate 0x10 typedef int DistributorHandle; typedef int PackageHandle; #define REPORT_MAX_MSG_LEN 128 /* Use the following macro in order to pass the private severity as the */ /* severity parameter to one of the Report routines */ #define SET_PRIVATE_DISTRIBUTOR(handle) (ErrorSeverity)(Private | ((handle)<<5)) /* The following are some constant for control and manipulation throughout the */ /* Report's control routines */ #define REPORT_OFF 0 #define REPORT_ON 1 #define REPORT_REMOVE 0 #define REPORT_ADD 1 /* This is a prototype of the output hook. When adding a function to the distributor, */ /* the routine's prototype should be the same as here */ typedef int (* ReportFunction)(char *message, /* The formatted message */ char *FileName, int LineNumber, int errorCode, /* error code that caused the report */ int parameter1, /* user parameter no. 1 */ int parameter2); /* user parameter no. 2 */ /* Initialization struct. Default values are below */ typedef struct{ int DistributorTaskPriority; /* The report task's priority */ int DistributorQueueMaxMsgs; /* Maximum number of messages in the queue */ int MaxNumberOfPrivateDistributors; /* Maximum number of private distributor */ int MaxNumOfFilterNames; /* Maximum number of filters to enable the applica */ }ReportInitParams; /* these values can be used as default in the above package configuration */ #define REPORT_TASK_PRIORITY 150 #define REPORT_MAX_FILTER_PACKAGES 20 #define REPORT_QUEUE_MAX_MSGS 100 /*----------------------------------------------------------------------------*/ /*---------------------- Report Tracing and Exceptions -----------------------*/ /*---------------------------- without filtering -----------------------------*/ /*----------------------------------------------------------------------------*/ //void SendStatusResponse (uint32_t Code, char *Token); /*************************************************************************** * * Name : ReportInit * * Function : PEPORT library init * * Notes : Should be called before any other function from the Report * package. * * Return value: OK or ERROR if malloc has failed or task creation has * failed **************************************************************************/ extern STATUS ReportInit(ReportInitParams InitParams); extern uint32_t ReportInitMessage(MessageContainer* requestContainer); extern void ReportStopReporting(void); extern uint32_t StopReportInitMessage(MessageContainer* requestContainer); uint32_t SetDebugLogCategoryFunc(MessageContainer* requestContainer); void SetupDebugDisributorsRequestFunc(MessageContainer* requestContainer); uint32_t ReportResetReason(void); uint32_t OpenLogFile(void); uint32_t CloseLogFile(void); bool isReportActive(void); uint32_t LogToFile(char *message, char *FileName, int LineNumber,int errorCode,int Severity,int parameter); uint32_t safeReport(char *message, char *FileName, int LineNumber,int errorCode,int Severity,int parameter1,int parameter2); /*************************************************************************** * * Name : Report * * Function : PEPORT main routine * * Notes : It is recommended to use one of the macros below (Debug * Tracing ) instead of using this routine directly. This * is because the macros support other benefits such: file * name, line number etc. * * Parameters: message - user's message * errorCode - should be the return code of the routine that * failed and made this report * severity - the error level * parameter1 - user params no.1 (for additional information) * parameter2 - another user param. * * Return value: OK or ERROR if failed to send to distributor **************************************************************************/ extern STATUS Report(const char *message, char *FileName, int LineNumber, int errorCode, ErrorSeverity severity, int parameter1, int parameter2); /*************************************************************************** * * Name : ReportMessage2SysDist * * Function : Report a message to the System distributor * * Notes : The severity of this report is always * * Return value: OK or ERROR if failed to send to distributor **************************************************************************/ extern STATUS ReportMessage2SysDist(const char *message); /*************************************************************************** * * Name : ReportFormatMessage2SysDist * * Function : Report a formatted message (like printf) to the System * distributor * * Notes : The severity of this report is always * IMPORTANT: the formatting is done in the context of the * calling task!! * * Return value: OK or ERROR if failed to send to distributor **************************************************************************/ extern STATUS ReportFormatMessage2SysDist(const char *format, ...); /*************************************************************************** * * Name : ReportMessage2Dist * * Function : Report a message to the appropriate distributor * * Notes : The distributor handle should be passed using the macro * SET_PRIVATE_DISTRIBUTOR * * Return value: OK or ERROR if failed to send to distributor **************************************************************************/ extern STATUS ReportMessage2Dist(DistributorHandle distributor, const char *message); /*************************************************************************** * * Name : REPORT_ERR * * Function : Report an error * * Notes : Attention: this is a macro. Will add the file name & the * line number where the error is reported * * Parameters : See above, Report. * * Return value: OK; or Report's return code **************************************************************************/ #define REPORT_ERR(msg, error, severity, par1, par2) \ Report(REPORT_LINE(msg), error, severity, par1, par2) /*************************************************************************** * * Name : REPORT_IF_ERROR * * Function : if is TRUE then report an error * * Notes : Attention: this is a macro. Will add the file name & the * line number where the error is reported * * Parameters : See above, Report. * * Return value: OK; or Report's return code **************************************************************************/ #define REPORT_IF_ERROR(condition, msg, error, severity, par1, par2) \ ((condition) ? Report(msg, __FILE__,__LINE__, error, severity, par1, par2) : OK) /*----------------------------------------------------------------------------*/ /*---------------------- Report Tracing and Exceptions -----------------------*/ /*----------------------------- with filtering -------------------------------*/ /*----------------------------------------------------------------------------*/ /*************************************************************************** * * Name : ReportWithPackageFilter * * Function : PEPORT with package filter - main routine * * Notes : It is recommended to use one of the macros below instead * of using this routine directly. This is because the macros * support other benefits such: file name, line number etc. * * Parameters: ReportPackageHandle - filter's handle * message - user's message * errorCode - should be the return code of the routine * that failed and made this report * severity - the error level * parameter1 - user params no.1 (for additional * information) * parameter2 - another user param. * * Return value: OK or ERROR if failed to send to distributor **************************************************************************/ extern STATUS ReportWithPackageFilter(PackageHandle ReportPackageHandle, const char *message, char *FileName, int LineNumber, int errorCode, ErrorSeverity severity, int parameter1, int parameter2); /*************************************************************************** * * Name : ReportPackageMessage2SysDist * * Function : Report a message to the System distributor if the handle * is not filtered * * Notes : The severity of this report is always * * Return value: OK or ERROR if failed to send to distributor **************************************************************************/ /*extern STATUS ReportPackageMessage2SysDist(PackageHandle ReportPackageHandle, const char *message); */ /*************************************************************************** * * Name : ReportFormatPackageMessage2SysDist * * Function : Report a formatted message (like printf) to the output * if handle is not filtered * * Notes : The severity of this report is always * IMPORTANT: the formatting is done in the context of the * calling task!! * * Return value: OK or ERROR if failed to send to distributor **************************************************************************/ /*extern STATUS ReportFormatPackageMessage2SysDist(PackageHandle ReportPackageHandle, const char *format, ...); */ /*************************************************************************** * * Name : REPORT_ERR_FILTER * * Function : Report an error if handle is not filtered * * Notes : Attention: this is a macro. Will add the file name & the * line number where the error is reported * * Parameters : See above, Report. * * Return value: OK; or Report's return code **************************************************************************/ #define REPORT_ERR_FILTER(handle, msg, FileName, LineNumber,error, severity, par1, par2) \ ReportWithPackageFilter(handle, REPORT_LINE(msg), FileName, LineNumber,error, severity, par1, par2) /*************************************************************************** * * Name : REPORT_IF_ERROR_FILTER * * Function : if is TRUE and handle is not filtered * then report an error * * Notes : Attention: this is a macro. Will add the file name & the * line number where the error is reported * * Parameters : See above, Report. * * Return value: OK; or Report's return code **************************************************************************/ #define REPORT_IF_ERROR_FILTER(condition, handle, msg, FileName, LineNumber,error, severity, par1, par2) \ ((condition) ? REPORT_ERR_FILTER(handle,msg,FileName, LineNumber,error,severity,par1,par2) : OK) /*************************************************************************** * * Name : ReportAddFilterPackage * * Function : Add a package filter to the package filter's data base * * Notes : * * Parameters : filterName - The filter's name must be up to 10 letters * long * * Return value: The new filter handle; or -1 in case of an ERROR, thus: * errno = REPORT_ERROR_NAME_TOO_LONG in case of long name, * errno = REPORT_ERROR_TABLE_FULL if there are already too * many filters, * errno = REPORT_ERROR_NAME_EXISTS if the filterName already exists. **************************************************************************/ extern PackageHandle ReportAddFilterPackage(const char *filterName); /*************************************************************************** * * Name : ReportRemoveFilterPackage * * Function : Remove a package filter from the package filter's data base * * Notes : * * Parameters : filterName - The filter's name must be up to 10 letters * long * * Return value: OK; or ERROR and thus errno is set to one of the following: * errno = REPORT_ERROR_NAME_TOO_LONG in case of long name, * errno = REPORT_ERROR_NAME_ALREADY_DISABLE if the filter was * already removed, * errno = REPORT_ERROR_NAME_NOT_EXISTS if the filterName not exists. **************************************************************************/ extern STATUS ReportRemoveFilterPackage(const char *filterName); /*************************************************************************** * * Name : ReportSwitchPackageFilter * * Function : Switch the filter of the given handle * * Notes : REPORT_ON - filter is active. messages do not discarded. * REPORT_OFF - filter is not active. Its messages are discarded. * * Return value: OK; or ERROR if wrong handle **************************************************************************/ extern STATUS ReportSwitchPackageFilter(PackageHandle ReportPackageHandle, uint32_t SwitchOnOff); bool ReportFilterTest(uint8_t filterHandle); /*----------------------------------------------------------------------------*/ /*---------------------------- Distributor -----------------------------------*/ /*----------------------------------------------------------------------------*/ /*************************************************************************** * * Name : ReportAddDistributor * * Function : Add private distributor * * Notes : * * Parameters: distributorName - The name must be up to 10 letters long * * Return value: The new distributor handle, or -1 and thus: * errno = REPORT_ERROR_NAME_TOO_LONG in case of long name, * errno = REPORT_ERROR_TABLE_FULL if there are already too * many distributors, * errno = REPORT_ERROR_NAME_EXISTS if the distributorName * already exists. **************************************************************************/ extern DistributorHandle ReportAddDistributor(const char *distributorName); /*************************************************************************** * * Name : ReportRemoveDistributor * * Function : Remove private distributor * * Notes : The distributor's messages will be discarded. * Its name will be no longer seen in the distributor's list * when the REP_CONTROL is typed in the Monitor. * * Parameters: distributorName - The severity's name must be up to 10 * letters long. * * Return value: OK; or ERROR and thus errno is set to one of the following: * errno = REPORT_ERROR_NAME_TOO_LONG in case of long name, * errno = REPORT_ERROR_NAME_ALREADY_DISABLE if the distributor * was already removed, * errno = REPORT_ERROR_NAME_NOT_EXISTS if the distributorName * not exists. **************************************************************************/ extern DistributorHandle ReportRemoveDistributor(const char *distributorName); /*************************************************************************** * * Name : ReportDistributorControl * * Function : Disable / enable the flow of reports given its private * severity * * Notes : Disable reports using the constant REPORT_OFF * Enable the reports using the constant REPORT_ON * * Return value: OK or ERROR if illegal Distributor **************************************************************************/ extern STATUS ReportDistributorControl(DistributorHandle Distributor, uint32_t SwitchOnOff); /*----------------------------------------------------------------------------*/ /*------------------------ Message Distributor -------------------------------*/ /*----------------------------------------------------------------------------*/ /*************************************************************************** * * Name : ReportFd * * Function : Add or remove a file descriptor to/from the output distributor * * Notes : * * Parameters: fd - file descriptor. Supplied by the user * SwitchAddRemove - REPORT_ADD to add the fd * REPORT_REMOVE to remove it. * Distributor - 0 if not concerned with any private * severity, or the private severity's handle * to set with the given fd * * Return value: OK or ERROR with: * errno = REPORT_ERROR_NOT_ENOUGH_MEMORY if destination list * is full * errno = REPORT_ERROR_ILLEGAL_PARAMETER if (fd == -1) or * not found if asked to remove **************************************************************************/ extern STATUS ReportFd(int fd, uint32_t SwitchAddRemove, DistributorHandle Distributor); /*************************************************************************** * * Name : ReportFunc * * Function : Add or remove an output routine to/from the distributor * * Notes : * * Parameters: func - hook to the routine. Supplied by the user . * SwitchAddRemove - REPORT_ADD to add the hook * REPORT_REMOVE to remove it. * Distributor - Set 0 if not concerned with any private * severity, or give the private severity's * handle to set with the given fd. * * Return value: OK or ERROR with: * errno = REPORT_ERROR_NOT_ENOUGH_MEMORY if destination list * is full * errno = REPORT_ERROR_ILLEGAL_PARAMETER if (func == NULL) **************************************************************************/ extern STATUS ReportFunc(ReportFunction func, uint32_t SwitchAddRemove, DistributorHandle Distributor); /*************************************************************************** * * Name : ReportMonitorFunc * * Function : Add/remove an output routine that prints to the monitor * * Notes : Hiding Report messages from appearing on the monitor is * enable when the HALT> prompt is shown (by pressing ). * The filtering is done using an internal routine. * This routine can be added/removed using this call. * It can be added either to the regular distributor or to each * of the private distributors * * Parameters: SwitchAddRemove - REPORT_ADD to add the routine * REPORT_REMOVE to remove it. * Distributor - Set 0 if not concerned with any private * severity, or give the private severity's * handle to set with it . * * Return value: void **************************************************************************/ extern void ReportMonitorFunc(uint32_t SwitchAddRemove, uint32_t Distributor); /*----------------------------------------------------------------------------*/ /*------------------------------ Severity ------------------------------------*/ /*----------------------------------------------------------------------------*/ /*************************************************************************** * * Name : ReportSeveritySet * * Function : Determine the filter level of the message's severity * * Notes : Messages with severity below this level wont be sent to * their output * It does not affect the private severities * * Return value: void **************************************************************************/ extern void ReportSeveritySet(ErrorSeverity level); /*----------------------------------------------------------------------------*/ #define S1(x) #x #define S2(x) S1(x) //#define LOCATION __FILE__ " : " S2(__LINE__) #define REPORT_LINE(message) __FILE__ "." S2(__LINE__) ":t"S2(UsersysTickGet())" : " S2(message) //#define REPORT_LINE(message) __FILE__ "." _ASSERT_STR(__LINE__) ": " message /*----------------------------------------------------------------------------*/ /*---------------------- Backward Support to UT_Except -----------------------*/ /*----------------------------------------------------------------------------*/ #define ON_ERROR_REPORT_MSG(msg) if ( rc != 0 ) \ Report("ERROR :" msg,__FILE__,__LINE__,rc,RpWarning,0,0) #define REPORT_MSG(rc,msg) \ Report("MSG : " msg,__FILE__,__LINE__,rc,RpWarning,0,0) #define ON_ERROR_LOG_ERROR(msg) if ( rc != 0 ) \ Report("ERROR :" msg,__FILE__,__LINE__,rc,RpError,0,0) #define LOG_ERROR(rc,msg) \ Report("ERROR :" msg,__FILE__,__LINE__,rc,RpError,0,0) /*----------------------------------------------------------------------------*/ /*----------------------- Backward Compatible --------------------------------*/ /*----------------------------------------------------------------------------*/ extern STATUS ReportMessage(const char *message); extern STATUS Reportf(const char *format, ...); #define ReportFilterMessage ReportPackageMessage2SysDist /*----------------------------------------------------------------------------*/ /*---------------------------- Error Codes -----------------------------------*/ /*----------------------------------------------------------------------------*/ /* Error, returned by errno in Report's routines */ #define REPORT_ERROR_ILLEGAL_PARAMETER 1 #define REPORT_ERROR_CODE_NOT_FOUND 2 #define REPORT_ERROR_FILTER_NOT_ALIVE 3 #define REPORT_ERROR_NAME 10 #define REPORT_ERROR_NAME_EXISTS 11 #define REPORT_ERROR_NAME_NOT_EXISTS 12 #define REPORT_ERROR_NAME_TOO_LONG 13 #define REPORT_ERROR_NAME_ALREADY_DISABLE 14 #define REPORT_ERROR_NOT_ENOUGH_MEMORY 20 #define REPORT_ERROR_TABLE_FULL 21 #ifdef __cplusplus } #endif #endif /* __REPORT_H__ */