From e973483cc8ae26e600dc6707d3e901d849a080ce Mon Sep 17 00:00:00 2001
From: mrdudz <mrdudz@users.noreply.github.com>
Date: Fri, 11 Jul 2025 21:55:58 +0200
Subject: [PATCH 1/3] DbgIsBreak() must use __cdecl__

---
 libsrc/dbg/dbg.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libsrc/dbg/dbg.c b/libsrc/dbg/dbg.c
index dd47eae0c..33583fbdc 100644
--- a/libsrc/dbg/dbg.c
+++ b/libsrc/dbg/dbg.c
@@ -332,7 +332,7 @@ BreakPoint DbgBreaks [MAX_USERBREAKS+2];
 BreakPoint* DbgGetBreakSlot (void);
 /* Search for a free breakpoint slot. Return a pointer to the slot or 0 */
 
-BreakPoint* DbgIsBreak (unsigned Addr);
+BreakPoint* __cdecl__ DbgIsBreak (unsigned Addr);
 /* Check if there is a user breakpoint at the given address, if so, return
 ** a pointer to the slot, else return 0.
 */

From 0d30d8b4ae5b776ca12acb9d48c905cede851cd3 Mon Sep 17 00:00:00 2001
From: mrdudz <mrdudz@users.noreply.github.com>
Date: Fri, 11 Jul 2025 21:56:34 +0200
Subject: [PATCH 2/3] add (very simple) example for dbg.h

---
 samples/Makefile | 11 +++++++++++
 samples/debug.c  | 12 ++++++++++++
 2 files changed, 23 insertions(+)
 create mode 100644 samples/debug.c

diff --git a/samples/Makefile b/samples/Makefile
index faa0de906..52e651bfc 100644
--- a/samples/Makefile
+++ b/samples/Makefile
@@ -193,6 +193,7 @@ EXELIST_agat =     \
 EXELIST_apple2 =   \
         ascii      \
         checkversion \
+        debug      \
         diodemo    \
         enumdevdir \
         gunzip65   \
@@ -212,6 +213,7 @@ EXELIST_apple2enh = $(EXELIST_apple2)
 EXELIST_atari =    \
         ascii      \
         checkversion \
+        debug      \
         gunzip65   \
         hello      \
         mandelbrot \
@@ -250,6 +252,7 @@ EXELIST_bbc = \
 EXELIST_c64 =      \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         gunzip65   \
         hello      \
@@ -275,6 +278,7 @@ EXELIST_c65 = \
 EXELIST_c128 =     \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         gunzip65   \
         hello      \
@@ -289,6 +293,7 @@ EXELIST_c128 =     \
 EXELIST_c16 =      \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         tinyshell  \
         hello      \
@@ -297,6 +302,7 @@ EXELIST_c16 =      \
 EXELIST_cbm510 =   \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         gunzip65   \
         hello      \
@@ -309,6 +315,7 @@ EXELIST_cbm510 =   \
 EXELIST_cbm610 =   \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         gunzip65   \
         hello      \
@@ -323,6 +330,7 @@ EXELIST_creativision = \
 EXELIST_cx16 =     \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         gunzip65   \
         hello      \
@@ -371,6 +379,7 @@ EXELIST_pce = \
 EXELIST_pet =      \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         hello      \
         joydemo    \
@@ -380,6 +389,7 @@ EXELIST_pet =      \
 EXELIST_plus4 =    \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         gunzip65   \
         hello      \
@@ -421,6 +431,7 @@ EXELIST_telestrat = \
 EXELIST_vic20 =    \
         ascii      \
         checkversion \
+        debug      \
         enumdevdir \
         hello      \
         joydemo    \
diff --git a/samples/debug.c b/samples/debug.c
new file mode 100644
index 000000000..f32a472fe
--- /dev/null
+++ b/samples/debug.c
@@ -0,0 +1,12 @@
+
+#include <dbg.h>
+
+int main(void)
+{
+    /* DbgInit has to be called once, to install the BRK handler */
+    DbgInit(0);
+
+    /* now to break into the debugger, use the BREAK macro */
+    BREAK();
+    return 0;
+}

From c0e8835ba054a4bc91a93d50d29ad0e79a56a589 Mon Sep 17 00:00:00 2001
From: mrdudz <mrdudz@users.noreply.github.com>
Date: Fri, 11 Jul 2025 22:32:14 +0200
Subject: [PATCH 3/3] brief docs

---
 doc/funcref.sgml | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/doc/funcref.sgml b/doc/funcref.sgml
index 9138e132f..6561c13ec 100644
--- a/doc/funcref.sgml
+++ b/doc/funcref.sgml
@@ -369,9 +369,14 @@ function.
 
 <sect1><tt/dbg.h/<label id="dbg.h"><p>
 
-<!-- <itemize> -->
-<!-- <item><ref id="DbgInit" name="DbgInit"> -->
-<!-- </itemize> -->
+<itemize>
+<item><ref id="DbgInit" name="DbgInit">
+<!-- <item><ref id="BREAK" name="BREAK"> -->
+<!-- <item><ref id="DbgDisAsm" name="DbgDisAsm"> -->
+<!-- <item><ref id="DbgDisAsmLen" name="DbgDisAsmLen"> -->
+<!-- <item><ref id="DbgIsRAM" name="DbgIsRAM"> -->
+<!-- <item><ref id="DbgMemDump" name="DbgMemDump"> -->
+</itemize>
 
 (incomplete)
 
@@ -3472,6 +3477,24 @@ used in presence of a prototype.
 </quote>
 
 
+<sect1>DbgInit<label id="DbgInit"><p>
+
+<quote>
+<descrip>
+<tag/Function/Initialize the debugger.
+<tag/Header/<tt/<ref id="dbg.h" name="dbg.h">/
+<tag/Declaration/<tt/void __fastcall__ DbgInit (unsigned unused);/
+<tag/Description/<tt/DbgInit/ initializes the debugger.
+<tag/Notes/<itemize>
+<item>Use 0 as parameter.
+<item>The debugger will popup on next brk encountered.
+</itemize>
+<tag/Availability/cc65
+<tag/Example/None.
+</descrip>
+</quote>
+
+
 <sect1>decompress_lz4<label id="decompress_lz4"><p>
 
 <quote>