diff --git a/common/Kconfig b/common/Kconfig
index d60db80..57119dc 100644
--- a/common/Kconfig
+++ b/common/Kconfig
@@ -667,6 +667,8 @@
 	prompt "low level debug messages"
 	help
 	  Enable this to get low level debug messages during barebox initialization.
+	  This requires SoC specific support. Most SoCs require the debug UART to be
+	  initialized by a debugger or first stage bootloader.
 
 endmenu
 
diff --git a/include/debug_ll.h b/include/debug_ll.h
index c5f2df4..f0034ba 100644
--- a/include/debug_ll.h
+++ b/include/debug_ll.h
@@ -1,4 +1,5 @@
-/* debug_ll.h
+/*
+ * debug_ll.h
  *
  *  written by Marc Singer
  *  12 Feb 2005
@@ -20,6 +21,14 @@
 #define   __INCLUDE_DEBUG_LL_H__
 
 #if defined (CONFIG_DEBUG_LL)
+
+/*
+ * mach/debug_ll.h should implement PUTC_LL. This can be a macro or a static
+ * inline function. Note that several SoCs expect the UART to be initialized
+ * by a debugger or a first stage bootloader. You won't see anything without
+ * this initialization. Depending on the PUTC_LL implementation the board might
+ * also hang in PUTC_LL without proper initialization.
+ */
 # include <mach/debug_ll.h>
 
 # define PUTHEX_LL(value)  ({ unsigned long v = (unsigned long) (value); \
@@ -29,6 +38,11 @@
 			     ch += (ch >= 10) ? 'a' - 10 : '0';\
 			     PUTC_LL (ch); }})
 
+/*
+ * Be careful with PUTS_LL, it only works if the binary is running at the
+ * link address which often is not the case during early startup. If in doubt
+ * don't use it.
+ */
 static __inline__ void PUTS_LL(const char * str)
 {
 	while (*str) {