py/mpprint.h: Add MP_PRN() macro.

py/mpprint.h: Rename MP_PRN to MP_DEBUG_PRINT.

Move MP_DEBUG_PRINT_XXX constants upper to the #if MICROPY_INCLUDED_PY_MPPRINT_H/#endif block.

Co-Authored-By: Andrew Leech <3318786+andrewleech@users.noreply.github.com>

py/mpprint.h: Fix typo.

py/mpprint.h: Move HOWTO  upper.

Add gaps between MP_DEBUG_PRINT_XXX levels.
Move `How to use:` upper before #define MP_DEBUG_PRINT().
Print level names instead of the numbers.

Signed-off-by: Ihor Nehrutsa <IhorNehrutsa@gmail.com>

py/mpprint.h: Move HOWTO  upper.

Add gaps between MP_DEBUG_PRINT_XXX levels.
Move `How to use:` upper before #define MP_DEBUG_PRINT().
Print level names instead of the numbers.

Signed-off-by: Ihor Nehrutsa <IhorNehrutsa@gmail.com>

py/mpprint.h: Fix typo.

py/mpprint.h: Rename MP_PRN to MP_DEBUG_PRINT.

Move MP_DEBUG_PRINT_XXX constants upper to the #if MICROPY_INCLUDED_PY_MPPRINT_H/#endif block.

py/mpprint.h: Add MP_PRN() macro.

Co-Authored-By: Andrew Leech <3318786+andrewleech@users.noreply.github.com>

py/mpprint.h

@@ -79,4 +79,78 @@ int mp_printf(const mp_print_t *print, const char *fmt, ...);
 int mp_vprintf(const mp_print_t *print, const char *fmt, va_list args);
 #endif
 
+// Debug messages during code developing with MP_DEBUG_PRINT(level, ...) & MP_DEBUG_PRINT_LEVEL.
+// An approximate hierarchy of debug levels MP_DEBUG_PRINT_LEVEL is:
+#define MP_DEBUG_PRINT_SUPPRESS 0 // SUPPRESS all messages. Use it in the release version.
+#define MP_DEBUG_PRINT_CRITICAL 10 // For the most CRITICAL errors, often requiring a system reset. Use a message with this level, if possible, raising an exception.
+#define MP_DEBUG_PRINT_ERROR 20 // ERROR requiring program restart, use message with this level before raising an exception.
+#define MP_DEBUG_PRINT_WARNING 30 // WARNING, something went wrong, but you can fix it with additional operations in code right now or may ignore it.
+#define MP_DEBUG_PRINT_INFO 40 // INFO, it is interesting and useful for understanding a bug.
+#define MP_DEBUG_PRINT_DEBUG 50 // DEBUG, more detailed information, dig deeper.
+#define MP_DEBUG_PRINT_TRACE 60 // TRACE, show a flow of the algorithm, like enter/exit a function.
+// In reality, you may use your own classification of debug levels.
+
 #endif // MICROPY_INCLUDED_PY_MPPRINT_H
+
+// This code is placed after `#endif // MICROPY_INCLUDED_PY_MPPRINT_H` to allow the developer
+// to use several local `MP_DEBUG_PRINT_LEVEL` definitions in separate _.c files.
+// This is not a typo or a bug.
+
+/*
+// Debugging macro for developers.
+
+// How to use:
+// Important! Set MP_DEBUG_PRINT_LEVEL in *.c or *.cpp development file BEFORE any "MicroPython's *.h" includes.
+// For example:
+#define MP_DEBUG_PRINT_LEVEL MP_DEBUG_PRINT_TRACE // show all messages
+// Include mpprint.h after defining the MP_DEBUG_PRINT_LEVEL
+#include "py/mpprint.h"
+...
+#include "py/obj.h"
+#include "py/runtime.h"
+...
+
+// Add MP_DEBUG_PRINT() macro in code, like
+void foo(int arg) {
+    MP_DEBUG_PRINT(MP_DEBUG_PRINT_TRACE, "Enter foo()")
+    if (arg < 0) {
+        MP_DEBUG_PRINT(MP_DEBUG_PRINT_WARNING, "arg=%d less zero", arg)
+        ...
+    }
+    ...
+    int value;
+    ...
+    // calculate value
+    ...
+    MP_DEBUG_PRINT(MP_DEBUG_PRINT_INFO, "See a value=%d", value)
+    ...
+    MP_DEBUG_PRINT(MP_DEBUG_PRINT_TRACE, "Exit foo()")
+}
+
+// It is not a dogma. You may start debugging from level 30.
+#define MP_DEBUG_PRINT_LEVEL 30
+// Then add MP_DEBUG_PRINT(30, ...) and when gets too many messages then change some messages to the next level MP_DEBUG_PRINT(40, ...), or MP_DEBUG_PRINT(20, ...) etc.
+// Then you may change MP_DEBUG_PRINT_LEVEL to 20(reduce printing), and finally to 0(suppress printing).
+
+// Usually, you will debug one or two source files. Debug printing from other files is suppressed if MP_DEBUG_PRINT_LEVEL is 0 or undefined.
+*/
+#if defined(MP_DEBUG_PRINT_LEVEL) && (MP_DEBUG_PRINT_LEVEL > 0)
+
+#if defined(MP_DEBUG_PRINT)
+#undef MP_DEBUG_PRINT
+#endif
+
+#define MP_DEBUG_PRINT(level, ...) \
+    do { \
+        if ((0 < level) && (level <= MP_DEBUG_PRINT_LEVEL)) { \
+            mp_printf(MP_PYTHON_PRINTER, " %s: ", #level); \
+            mp_printf(MP_PYTHON_PRINTER, __VA_ARGS__); \
+            mp_printf(MP_PYTHON_PRINTER, "\t : FUNC=%s LINE=%d FILE=%s\n", __FUNCTION__, __LINE__, __FILE__); \
+        } \
+    } while (0);
+
+#else
+
+#define MP_DEBUG_PRINT(level, ...)
+
+#endif