Add debug library; use with tmimsp platforms

[tinyos-2.x.git] / tos / lib / debug / Debug.h

diff --git a/tos/lib/debug/Debug.h b/tos/lib/debug/Debug.h
new file mode 100644 (file)
index 0000000..e9be7cf
--- /dev/null
+++ b/tos/lib/debug/Debug.h
@@ -0,0 +1,67 @@
+/* Copyright (c) 2006-2009 by Sporian Microsystems, Inc.
+ * All Rights Reserved.
+ *
+ * This document is the proprietary and confidential property of Sporian
+ * Microsystems, Inc.  All use, distribution, reproduction or re-distribution
+ * is disallowed without the prior express written consent of Sporian
+ * Microsystems, Inc.
+ */
+
+/**
+ * TinyOS debug layer offering printf-style functionality.
+ *
+ * @author R. Steve McKown <rsmckown@gmail.com>
+ *
+ * For a module to use the debug functions it must:
+ *
+ * 1. use the Debug interface, which is then wired to DebugC.
+ * 2. include "Debug.h" to set the macros appropriately.
+ *
+ * Optionally, a module may implement module specific debug, where a different
+ * global define can be used to individually select debug on or off for each
+ * module.  This feature requires the following lines of code in the module,
+ * after Debug.h has been included.  MODULENAME_DEBUG should be changed to a
+ * more meaningful, and module-unique, name, such as MYMODULE_DEBUG.
+ *
+ *    #ifndef SERIAL_DEBUG
+ *    #  undef MODULENAME_DEBUG
+ *    #else
+ *    #  ifndef MODULENAME_DEBUG
+ *    #    include "Debug_undef.h"
+ *    #  endif
+ *    #endif
+ *
+ * To activate debug for a program, add this line to the Makefile:
+ *    CFLAGS += -DSERIAL_DEBUG
+ *
+ * To activate debug for a module with selectable debug, one must additionally
+ * define the modules debug identifier in the Makefile, such as:
+ *    CFLAGS += -DMODULENAME_DEBUG
+ *
+ * Undefining SERIAL_DEBUG deactivates all program debug regardless of the state
+ * of any module-specific debug identifiers.
+ *
+ * Debug.h must no include the traditional multiple-inclusion guard so that each
+ * module including Debug.h has the opportunity to either set or clear (i.e.
+ * make a noop) the debug macros, according to the operating state defined for
+ * that module.
+ */
+
+#undef dbg_printf
+#undef dbg_assert
+
+#ifdef SERIAL_DEBUG
+
+#include <stdio.h>
+#include <stdarg.h>
+
+#define dbg_printf(args...) uprintf(call Debug.uptr(), args)
+#define dbg_assert(condition, args...) \
+    do { if (condition) uprintf(call Debug.uptr(), args); } while(0)
+
+#else
+
+#define dbg_printf(args...) ((void)0)
+#define dbg_assert(condition, args...) ((void)0)
+
+#endif