path: root/Software/Embedded_SW/Embedded/Common/report/report.h

/******************************************************************************
 * 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 <assert.h>         /* _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 <Message>
 *
 *  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 <Message>
 *                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 <condition> 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 <Message>
 *
 *  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 <Message>
 *                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 <condition> 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 <ENTER>).
 *                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__ */