Andrew Reed
/
CITY1082-i2c_master_wifi_mqtt
CITY3032-wifi-mqtt
connectivity-utilities/cy_log/cy_log.h
- Committer:
- reedas
- Date:
- 2021-11-13
- Revision:
- 5:f62a9e4a499a
- Parent:
- 4:7ebc3d28bcb2
File content as of revision 5:f62a9e4a499a:
/* * Copyright 2019-2021, Cypress Semiconductor Corporation (an Infineon company) or * an affiliate of Cypress Semiconductor Corporation. All rights reserved. * * This software, including source code, documentation and related * materials ("Software") is owned by Cypress Semiconductor Corporation * or one of its affiliates ("Cypress") and is protected by and subject to * worldwide patent protection (United States and foreign), * United States copyright laws and international treaty provisions. * Therefore, you may use this Software only as provided in the license * agreement accompanying the software package from which you * obtained this Software ("EULA"). * If no EULA applies, Cypress hereby grants you a personal, non-exclusive, * non-transferable license to copy, modify, and compile the Software * source code solely for use in connection with Cypress's * integrated circuit products. Any reproduction, modification, translation, * compilation, or representation of this Software except as specified * above is prohibited without the express written permission of Cypress. * * Disclaimer: THIS SOFTWARE IS PROVIDED AS-IS, WITH NO WARRANTY OF ANY KIND, * EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, NONINFRINGEMENT, IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Cypress * reserves the right to make changes to the Software without notice. Cypress * does not assume any liability arising out of the application or use of the * Software or any product or circuit described in the Software. Cypress does * not authorize its products for use in any products where a malfunction or * failure of the Cypress product may reasonably be expected to result in * significant property damage, injury or death ("High Risk Product"). By * including Cypress's product in a High Risk Product, the manufacturer * of such system or application assumes all risk of such use and in doing * so agrees to indemnify Cypress against all liability. */ /** * @file * @addtogroup logging_utils * * A logging subsystem that allows run time control for the logging level. * Log messages are passed back to the application for output. * Log messages are given sequence numbers. * A time callback can be provided by the application for the timestamp for each output line. * Log messages are mutex protected across threads so that log messages do not interrupt each other. */ /* * in Main application file: * * Log output callback function - The App decides what and how logging is to be output * * int app_log_output_callback(CY_LOG_FACILITY_T facility, CY_LOG_LEVEL_T level, char *logmsg) * { * (void)facility; // Can be used to decide to reduce output or send output to remote logging * (void)level; // Can be used to decide to reduce output, although the output has already been * // limited by the log routines * * return printf( "%s\n", logmsg); // print directly to console * } * * * Log time callback - get the current time for the log message timestamp in millseconds * * cy_rslt_t app_log_time(uint32_t* time) * { * if (time != NULL) * { * *time = get_time_ms(); // get system time (in milliseconds) * } * return CY_RSLT_SUCCESS; * } * * * Log initialization - default os OFF, no output from any facility * * result = cy_log_init(CY_LOG_OFF, app_log_output_callback, app_log_time); * if (result != CY_RSLT_SUCCESS) * { * printf("cy_log_init() FAILED %ld\n", result); * } * * * Example using TEST facility * * cy_log_set_facility_level(CYLF_TEST, CY_LOG_WARNING); // set log message level to WARNING * * cy_log_printf("TEST message: always print."); // Bypass facility/level check and always print message * // calls app_log_output_callback(CYLF_DEF, CY_LOG_PRINTF, logmsg) * * cy_log_msg(CYLF_TEST, CY_LOG_ERR, "TEST message: ERR"); // Print if CYLF_TEST level is CY_LOG_ERR or higher * cy_log_msg(CYLF_TEST, CY_LOG_WARNING, "TEST message: WARNING"); // Print if CYLF_TEST level is CY_LOG_WARNING or higher * cy_log_msg(CYLF_TEST, CY_LOG_NOTICE, "TEST message: NOTICE"); // Print if CYLF_TEST level is CY_LOG_NOTICE or higher * * cy_log_msg(CYLF_DRIVER, CY_LOG_ERR, "DRIVER message: ERR"); // Print if CYLF_DRIVER level is CY_LOG_ERR or higher * * OUTPUT: * * TEST message: always print. * TEST message: ERR * TEST message: WARNING * * - No other CYLF_TEST output due to level set as CY_LOG_WARNING * - No CYLF_DRIVER output due to level set as CY_LOG_OFF */ #pragma once #include <stdarg.h> #include "cy_result.h" #ifdef __cplusplus extern "C" { #endif /****************************************************** * Macros ******************************************************/ /****************************************************** * Constants ******************************************************/ /****************************************************** * Enumerations ******************************************************/ /******************************************************************************/ /** \addtogroup group_logging_enums * Documentation of the enums provided by logging utility. *//** \{ */ /******************************************************************************/ /** Logging levels. NOTE: Default value for all facilities is passed in to init call */ typedef enum { CY_LOG_OFF = 0, /**< Do not print log messages */ CY_LOG_ERR, /**< Print log message if run-time level is <= CY_LOG_ERR */ CY_LOG_WARNING, /**< Print log message if run-time level is <= CY_LOG_WARNING */ CY_LOG_NOTICE, /**< Print log message if run-time level is <= CY_LOG_NOTICE */ CY_LOG_INFO, /**< Print log message if run-time level is <= CY_LOG_INFO */ CY_LOG_DEBUG, /**< Print log message if run-time level is <= CY_LOG_DEBUG */ CY_LOG_DEBUG1, /**< Print log message if run-time level is <= CY_LOG_DEBUG1 */ CY_LOG_DEBUG2, /**< Print log message if run-time level is <= CY_LOG_DEBUG2 */ CY_LOG_DEBUG3, /**< Print log message if run-time level is <= CY_LOG_DEBUG3 */ CY_LOG_DEBUG4, /**< Print log message if run-time level is <= CY_LOG_DEBUG4 */ CY_LOG_PRINTF, /* Identifies log messages generated by cy_log_printf calls */ CY_LOG_MAX } CY_LOG_LEVEL_T; /** Log Facility type * Log facilities allow for separate subsystems to have different run-time log levels for output. * This allows for someone working in the Driver subsystem to turn on DEBUG level without turning DEBUG * level for middleware - makes for less unwanted output during debugging / testing. */ typedef enum { CYLF_DEF = 0, /**< General log message not associated with any specific Facility */ CYLF_TEST, /**< Test Facility */ CYLF_DRIVER, /**< Driver Facility */ CYLF_LP, /**< Low Power Facility */ CYLF_MIDDLEWARE, /**< Middleware Facility */ CYLF_AUDIO, /**< Audio Facility */ CYLF_MAX /**< Must be last, not an actual index */ } CY_LOG_FACILITY_T; /** \} */ /******************************************************************************/ /** \addtogroup group_logging_structures * Documentation of the typedefs defined by the logging utility. *//** \{ */ /******************************************************************************/ /****************************************************** * Structures ******************************************************/ /****************************************************** * Type Definitions ******************************************************/ /** Prototype for application callback to use the logging message */ typedef int (*log_output)(CY_LOG_FACILITY_T facility, CY_LOG_LEVEL_T level, char *logmsg); /** Prototype for application callback to get current time in milliseconds */ typedef cy_rslt_t (*platform_get_time)(uint32_t* time); /** \} */ /*****************************************************************************/ /** * * @addtogroup group_logging_func * * A logging subsystem provides a set of helper functions to manage logging in the application. * * @{ */ /*****************************************************************************/ /****************************************************** * Function Declarations ******************************************************/ /** Initialize the logging subsystem. * * @param[in] level : The initial logging level to use for all facilities. * @param[in] platform_output : Pointer to the function invoked by the library to output the log messages. * If this argument is passed as NULL, the library prints the log output on the standard output stream (stdio). * @param[in] platform_time : Pointer to the function invoked by the library to get the time. If this argument is passed as NULL, the library calls * [cy_rtos_get_time](https://cypresssemiconductorco.github.io/abstraction-rtos/html/group__group__abstraction__rtos__time.html) * function to get the time required for logging. * * @return cy_rslt_t */ cy_rslt_t cy_log_init(CY_LOG_LEVEL_T level, log_output platform_output, platform_get_time platform_time); /** Shutdown the logging subsystem. * * @return cy_rslt_t */ cy_rslt_t cy_log_shutdown(void); /** Set the platform output routine for log messages. * * @note If platform_output is NULL, log messages will be discarded. * * @param[in] platform_output : Pointer to the platform output routine for log messages. * * @return cy_rslt_t */ cy_rslt_t cy_log_set_platform_output(log_output platform_output); /** Set the platform routine for getting time stamps for log messages. * * @note If platform_time is NULL, cy_time_get_time() is used for time stamps. * * @param[in] platform_time : Pointer to a platform time routine for log message time stamps. * * @return cy_rslt_t */ cy_rslt_t cy_log_set_platform_time(platform_get_time platform_time); /** Set the logging level for a facility. * * @param[in] facility : The facility for which to set the log level. * @param[in] level : The new log level to use. * * @return cy_rslt_t */ cy_rslt_t cy_log_set_facility_level(CY_LOG_FACILITY_T facility, CY_LOG_LEVEL_T level); /** Set the logging level for all facilities. * * @param[in] level : The new log level to use. * * @return cy_rslt_t */ cy_rslt_t cy_log_set_all_levels(CY_LOG_LEVEL_T level); /** Get the logging level for a facility. * * @param[in] facility : The facility for which to return the log level. * * @return The current log level. */ CY_LOG_LEVEL_T cy_log_get_facility_level(CY_LOG_FACILITY_T facility); /** Write a log message. * * @note The format arguments are the same as for printf. * * @param[in] facility : The facility for the log message. * @param[in] level : Log level of the message. * @param[in] fmt : Format control string followed by any optional arguments. * * @return cy_rslt_t */ cy_rslt_t cy_log_msg(CY_LOG_FACILITY_T facility, CY_LOG_LEVEL_T level, const char *fmt, ...); /** Write a log message bypassing the log level check. * * @note The format arguments are the same as for printf. * * @param[in] fmt : Format control string followed by any optional arguments. * * @return cy_rslt_t */ cy_rslt_t cy_log_printf(const char *fmt, ...); /** Write a log message bypassing the log level check using va_list * * @note The format arguments are the same as for vprintf. * * @param[in] fmt : Format control string. * @param[in] varg : va_list of arguments. * * @return cy_rslt_t */ cy_rslt_t cy_log_vprintf(const char *fmt, va_list varg); /** @} */ #ifdef __cplusplus } /* extern "C" */ #endif