From 3ce61b47a9182860e0f91aa1c9c63f2bf21a19e9 Mon Sep 17 00:00:00 2001
From: "ol.sc" <ol.sc@b7a2c559-68d2-44c3-8de9-860c34a00d81>
Date: Thu, 19 Jul 2012 12:25:04 +0000
Subject: [PATCH] Retrofitted comments from GEOS overlay demo to regular
 overlay demo.

git-svn-id: svn://svn.cc65.org/cc65/trunk@5789 b7a2c559-68d2-44c3-8de9-860c34a00d81
---
 samples/overlaydemo.c | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/samples/overlaydemo.c b/samples/overlaydemo.c
index 318a32e63..9b049e9ef 100644
--- a/samples/overlaydemo.c
+++ b/samples/overlaydemo.c
@@ -18,16 +18,29 @@ extern void _OVERLAY2_LOAD__, _OVERLAY2_SIZE__;
 extern void _OVERLAY3_LOAD__, _OVERLAY3_SIZE__;
 
 
+/* Functions resident in an overlay can call back functions resident in the
+ * main program at any time without any precautions. The function log() is
+ * an example for such a function resident in the main program.
+ */
 void log (char *msg)
 {
     printf ("Log: %s\n", msg);
 }
 
 
+/* In a real-world overlay program one would probably not use a #pragma but
+ * rather place the all the code of certain source files into the overlay by
+ * compiling them with --code-name OVERLAY1.
+ */
 #pragma code-name (push, "OVERLAY1");
 
 void foo (void)
 {
+    /* Functions resident in an overlay can access all program variables and
+     * constants at any time without any precautions because those are never
+     * placed in overlays. The string constant below is an example for such 
+     * a constant resident in the main program.
+     */
     log ("Calling main from overlay 1");
 }
 
@@ -71,11 +84,25 @@ unsigned char loadfile (char *name, void *addr, void *size)
 void main (void)
 {
     log ("Calling overlay 1 from main");
+
+    /* The symbols _OVERLAY1_LOAD__ and _OVERLAY1_SIZE__ were generated by the
+     * linker. They contain the overlay area address and size specific to a
+     * certain program.
+     */
     if (loadfile ("ovrldemo.1", &_OVERLAY1_LOAD__, &_OVERLAY1_SIZE__)) {
+
+        /* The linker makes sure that the call to foo() ends up at the right mem
+         * addr. However it's up to user to make sure that the - right - overlay
+         * is actually loaded before making the the call.
+         */
         foo ();
     }
 
     log ("Calling overlay 2 from main");
+
+    /* Replacing one overlay with another one can only happen from the main
+     * program. This implies that an overlay can never load another overlay.
+     */
     if (loadfile ("ovrldemo.2", &_OVERLAY2_LOAD__, &_OVERLAY2_SIZE__)) {
         bar ();
     }
-- 
2.39.5