Allow overriding default definitions of logging macros (#384)

* Update logging_stack.h file to avoid use of __FUNCTION__ macro

* Revert to use __FUNCTION__ instead of __FILE__

* Fix comment about metadata format

* Fix incorrect mapping of SdkLog function

* Fix typo causing LOG_METADATA_ARGS to be undefined

* Fix another bug with SdkLog macro definition

* Fix formatting

* Move mapping of SdkLog to vLoggingPrintf from logging_stack to config files

* Remove dependency of LIBRARY_LOG_NAME on LIBRARY_METADATA_* macros

* Minor improvements

Co-authored-by: Gary Wicker <14828980+gkwicker@users.noreply.github.com>
Co-authored-by: RichardBarry <3073890+RichardBarry@users.noreply.github.com>

FreeRTOS-Plus/Demo/AWS/Device_Shadow_Windows_Simulator/Device_Shadow_Demo/core_mqtt_config.h

@@ -47,6 +47,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 /************ End of logging configuration ****************/
 

FreeRTOS-Plus/Demo/AWS/Device_Shadow_Windows_Simulator/Device_Shadow_Demo/demo_config.h

@@ -51,11 +51,24 @@
 #ifndef LIBRARY_LOG_LEVEL
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
+
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/
 
 #ifndef democonfigCLIENT_IDENTIFIER
+
 /**
  * @brief The MQTT client identifier used in this example.  Each client identifier
  * must be unique so edit as required to ensure no two clients connecting to the

FreeRTOS-Plus/Demo/AWS/Device_Shadow_Windows_Simulator/Device_Shadow_Demo/shadow_config.h

@@ -44,6 +44,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/core_mqtt_config.h

@@ -47,6 +47,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 /************ End of logging configuration ****************/
 

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Basic_TLS/demo_config.h

@@ -51,6 +51,18 @@
 #ifndef LIBRARY_LOG_LEVEL
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
+
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/core_mqtt_config.h

@@ -49,6 +49,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_NONE
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 /************ End of logging configuration ****************/
 

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Keep_Alive/demo_config.h

@@ -49,6 +49,18 @@
 #ifndef LIBRARY_LOG_LEVEL
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
+
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/core_mqtt_config.h

@@ -49,6 +49,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 /************ End of logging configuration ****************/
 

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Multitask/demo_config.h

@@ -48,6 +48,18 @@
 #ifndef LIBRARY_LOG_LEVEL
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
+
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/core_mqtt_config.h

@@ -47,6 +47,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 /************ End of logging configuration ****************/
 

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Mutual_Auth/demo_config.h

@@ -51,6 +51,18 @@
 #ifndef LIBRARY_LOG_LEVEL
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
+
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/core_mqtt_config.h

@@ -49,6 +49,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_NONE
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 /************ End of logging configuration ****************/
 

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Plain_Text/demo_config.h

@@ -49,6 +49,18 @@
 #ifndef LIBRARY_LOG_LEVEL
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
+
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/core_mqtt_config.h

@@ -49,6 +49,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 /************ End of logging configuration ****************/
 

FreeRTOS-Plus/Demo/coreMQTT_Windows_Simulator/MQTT_Serializer/demo_config.h

@@ -49,6 +49,18 @@
 #ifndef LIBRARY_LOG_LEVEL
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
+
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Demo/corePKCS11_MQTT_Mutual_Auth_Windows_Simulator/core_mqtt_config.h

@@ -47,6 +47,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 /************ End of logging configuration ****************/
 

FreeRTOS-Plus/Demo/corePKCS11_MQTT_Mutual_Auth_Windows_Simulator/core_pkcs11_config.h

@@ -56,6 +56,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /**

FreeRTOS-Plus/Demo/corePKCS11_MQTT_Mutual_Auth_Windows_Simulator/demo_config.h

@@ -51,6 +51,18 @@
 #ifndef LIBRARY_LOG_LEVEL
     #define LIBRARY_LOG_LEVEL    LOG_INFO
 #endif
+
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Demo/corePKCS11_Windows_Simulator/core_pkcs11_config.h

@@ -56,6 +56,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /**

FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/sockets_wrapper.h

@@ -53,6 +53,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/using_mbedtls/using_mbedtls.h

@@ -48,6 +48,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/using_mbedtls_pkcs11/using_mbedtls_pkcs11.h

@@ -51,6 +51,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Source/Application-Protocols/network_transport/freertos_plus_tcp/using_plaintext/using_plaintext.h

@@ -43,6 +43,17 @@
     #define LIBRARY_LOG_LEVEL    LOG_ERROR
 #endif
 
+/* Prototype for the function used to print to console on Windows simulator
+ * of FreeRTOS.
+ * The function prints to the console before the network is connected;
+ * then a UDP port after the network has connected. */
+extern void vLoggingPrintf( const char * pcFormatString,
+                            ... );
+
+/* Map the SdkLog macro to the logging function to enable logging
+ * on Windows simulator. */
+#define SdkLog( message )    vLoggingPrintf message
+
 #include "logging_stack.h"
 
 /************ End of logging configuration ****************/

FreeRTOS-Plus/Source/Utilities/logging/logging_levels.h

@@ -27,11 +27,11 @@
 
 /**
  * @file logging_levels.h
- * @brief Defines the logging level macros.
+ * @brief Defines the configuration constants for all logging verbosity levels.
  */
 
-#ifndef LOGGING_LEVELS_H_
+#ifndef LOGGING_LEVELS_H
-#define LOGGING_LEVELS_H_
+#define LOGGING_LEVELS_H
 
 /**
  * @constantspage{logging,logging library}
@@ -111,4 +111,4 @@
  */
 #define LOG_DEBUG    4
 
-#endif /* ifndef LOGGING_LEVELS_H_ */
+#endif /* ifndef LOGGING_LEVELS_H */

FreeRTOS-Plus/Source/Utilities/logging/logging_stack.h

@@ -27,35 +27,59 @@
 
 /**
  * @file logging_stack.h
- * @brief Reference implementation of Logging stack as a header-only library.
+ * @brief Utility header file that exposes macros for configuring logging implementation of logging macros (LogError, LogWarn, LogInfo, LogDebug).
  */
 
-#ifndef LOGGING_STACK_H_
+#ifndef LOGGING_STACK_H
-#define LOGGING_STACK_H_
+#define LOGGING_STACK_H
 
 /* Include header for logging level macros. */
 #include "logging_levels.h"
 
 /* Standard Include. */
+#include <stdio.h>
 #include <stdint.h>
 
+/**
+ * @brief The name of the library or demo to add as metadata in log messages
+ * from the library or demo.
+ *
+ * This metadata aids in identifying the module source of log messages.
+ * The metadata is logged in the format `[ <LIBRARY-NAME> ]` as a prefix to the
+ * log messages.
+ * Refer to #LOG_METADATA_FORMAT for the complete format of the metadata prefix in
+ * log messages.
+ */
+/* Check if LIBRARY_LOG_NAME macro has been defined. */
+#if !defined( LIBRARY_LOG_NAME )
+    #error "Please define LIBRARY_LOG_NAME for the library."
+#endif
+
 /* Metadata information to prepend to every log message. */
-#define LOG_METADATA_FORMAT    "[%s:%d] "
+#ifndef LOG_METADATA_FORMAT
-#define LOG_METADATA_ARGS      __FUNCTION__, __LINE__
+    #define LOG_METADATA_FORMAT    "[%s:%d] "                  /**< @brief Format of metadata prefix in log messages. */
+#endif
 
-/* Common macro for all logging interface macros. */
+#ifndef LOG_METADATA_ARGS
-#if !defined( DISABLE_LOGGING )
+    #define LOG_METADATA_ARGS    __FUNCTION__, __LINE__  /**< @brief Arguments into the metadata logging prefix format. */
+#endif
 
-/* Prototype for the function used to print out.  In this case it prints to the
+/**
- * console before the network is connected then a UDP port after the network has
+ * @brief Common macro that maps all the logging interfaces,
- * connected. */
+ * (#LogDebug, #LogInfo, #LogWarn, #LogError) to the platform-specific logging
-    extern void vLoggingPrintf( const char * pcFormatString,
+ * function.
-                                ... );
+ *
-    #define SdkLog( string )    vLoggingPrintf string
+ * @note The default definition of the macro is an empty definition that does not
-#else
+ * generate any logging.
+ */
+#ifndef SdkLog
     #define SdkLog( string )
 #endif
 
+/**
+ * Disable definition of logging interface macros when generating doxygen output,
+ * to avoid conflict with documentation of macros at the end of the file.
+ */
 /* Check that LIBRARY_LOG_LEVEL is defined and has a valid value. */
 #if !defined( LIBRARY_LOG_LEVEL ) ||       \
     ( ( LIBRARY_LOG_LEVEL != LOG_NONE ) && \
@@ -64,8 +88,6 @@
     ( LIBRARY_LOG_LEVEL != LOG_INFO ) &&   \
     ( LIBRARY_LOG_LEVEL != LOG_DEBUG ) )
     #error "Please define LIBRARY_LOG_LEVEL as either LOG_NONE, LOG_ERROR, LOG_WARN, LOG_INFO, or LOG_DEBUG."
-#elif !defined( LIBRARY_LOG_NAME )
-    #error "Please define LIBRARY_LOG_NAME for the library."
 #else
     #if LIBRARY_LOG_LEVEL == LOG_DEBUG
         /* All log level messages will logged. */
@@ -105,4 +127,4 @@
     #endif /* if LIBRARY_LOG_LEVEL == LOG_ERROR */
 #endif /* if !defined( LIBRARY_LOG_LEVEL ) || ( ( LIBRARY_LOG_LEVEL != LOG_NONE ) && ( LIBRARY_LOG_LEVEL != LOG_ERROR ) && ( LIBRARY_LOG_LEVEL != LOG_WARN ) && ( LIBRARY_LOG_LEVEL != LOG_INFO ) && ( LIBRARY_LOG_LEVEL != LOG_DEBUG ) ) */
 
-#endif /* ifndef LOGGING_STACK_H_ */
+#endif /* ifndef LOGGING_STACK_H */