Configuration options.

This commit contains the following changes:

* The value of `Z80_OPTION_HALT_SKIP` has been changed to 4. This makes room for a 2-bit integer in the most significant bits of `Z80::options`, which may be useful for future emulation of Soviet and MME chips.
* `Z80_WITH_RETX_NOTIFICATIONS_IN_IM0` has been renamed to `Z80_WITH_IM0_RETX_NOTIFICATIONS`.
* Added `Z80_OPTION_IM0_RETX_NOTIFICATIONS` for enabling at runtime the notifications of the execution of `reti` and `retn` during the interrupt mode 0 response.
* Updated the documentation accordingly.

Author: redcode

.github/workflows/build_and_test_library.yml

@@ -34,8 +34,8 @@ env:
   Z80_WITH_TESTS: YES
   Z80_WITH_EXECUTE: YES
   Z80_WITH_FULL_IM0: YES
+  Z80_WITH_IM0_RETX_NOTIFICATIONS: YES
   Z80_WITH_Q: YES
-  Z80_WITH_RETX_NOTIFICATIONS_IN_IM0: YES
   Z80_WITH_SPECIAL_RESET: YES
   Z80_WITH_UNOFFICIAL_RETI: NO
   Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG: YES
@@ -80,8 +80,8 @@ jobs:
         -DZ80_WITH_TESTS=${{env.Z80_WITH_TESTS}}
         -DZ80_WITH_EXECUTE=${{env.Z80_WITH_EXECUTE}}
         -DZ80_WITH_FULL_IM0=${{env.Z80_WITH_FULL_IM0}}
+        -DZ80_WITH_IM0_RETX_NOTIFICATIONS=${{env.Z80_WITH_IM0_RETX_NOTIFICATIONS}}
         -DZ80_WITH_Q=${{env.Z80_WITH_Q}}
-        -DZ80_WITH_RETX_NOTIFICATIONS_IN_IM0=${{env.Z80_WITH_RETX_NOTIFICATIONS_IN_IM0}}
         -DZ80_WITH_SPECIAL_RESET=${{env.Z80_WITH_SPECIAL_RESET}}
         -DZ80_WITH_UNOFFICIAL_RETI=${{env.Z80_WITH_UNOFFICIAL_RETI}}
         -DZ80_WITH_ZILOG_NMOS_LD_A_IR_BUG=${{env.Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG}}

API/Z80.h

@@ -447,21 +447,26 @@ typedef struct {
 
 #define Z80_OPTION_LD_A_IR_BUG 2
 
+/** @brief <tt>@ref Z80::options</tt> bitmask that enables the HALTskip
+  * optimization. */
+
+#define Z80_OPTION_HALT_SKIP 4
+
 /** @brief <tt>@ref Z80::options</tt> bitmask that enables the XQ factor in the
   * emulation of the @c ccf and @c scf instructions. */
 
 #define Z80_OPTION_XQ 8
 
+/** @brief <tt>@ref Z80::options</tt> bitmask that enables notifications for any
+`reti` or `retn` instruction executed during the interrupt mode 0 response. */
+
+#define Z80_OPTION_IM0_RETX_NOTIFICATIONS 16
+
 /** @brief <tt>@ref Z80::options</tt> bitmask that enables the YQ factor in the
   * emulation of the @c ccf and @c scf instructions. */
 
 #define Z80_OPTION_YQ 32
 
-/** @brief <tt>@ref Z80::options</tt> bitmask that enables the HALTskip
-  * optimization. */
-
-#define Z80_OPTION_HALT_SKIP 64
-
 /** @brief <tt>@ref Z80::options</tt> bitmask that enables full emulation of the
   * Zilog NMOS models. */
 

CMakeLists.txt

@@ -92,15 +92,15 @@ option(${PROJECT_NAME}_WITH_FULL_IM0
 reduced one."
 NO)
 
-option(${PROJECT_NAME}_WITH_Q
-"Build the implementation of Q."
-NO)
-
-option(${PROJECT_NAME}_WITH_RETX_NOTIFICATIONS_IN_IM0
+option(${PROJECT_NAME}_WITH_IM0_RETX_NOTIFICATIONS
 "Enable optional notifications for any `reti` or `retn` instruction \
 executed during the interrupt mode 0 response."
 NO)
 
+option(${PROJECT_NAME}_WITH_Q
+"Build the implementation of Q."
+NO)
+
 option(${PROJECT_NAME}_WITH_SPECIAL_RESET
 "Build the implementation of the special RESET."
 NO)
@@ -192,8 +192,8 @@ target_compile_definitions(
 	${PROJECT_NAME} PRIVATE
 	$<$<BOOL:${${PROJECT_NAME}_WITH_EXECUTE}>:Z80_WITH_EXECUTE>
 	$<$<BOOL:${${PROJECT_NAME}_WITH_FULL_IM0}>:Z80_WITH_FULL_IM0>
+	$<$<BOOL:${${PROJECT_NAME}_WITH_IM0_RETX_NOTIFICATIONS}>:Z80_WITH_IM0_RETX_NOTIFICATIONS>
 	$<$<BOOL:${${PROJECT_NAME}_WITH_Q}>:Z80_WITH_Q>
-	$<$<BOOL:${${PROJECT_NAME}_WITH_RETX_NOTIFICATIONS_IN_IM0}>:Z80_WITH_RETX_NOTIFICATIONS_IN_IM0>
 	$<$<BOOL:${${PROJECT_NAME}_WITH_SPECIAL_RESET}>:Z80_WITH_SPECIAL_RESET>
 	$<$<BOOL:${${PROJECT_NAME}_WITH_UNOFFICIAL_RETI}>:Z80_WITH_UNOFFICIAL_RETI>
 	$<$<BOOL:${${PROJECT_NAME}_WITH_ZILOG_NMOS_LD_A_IR_BUG}>:Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG>)

README

@@ -185,15 +185,15 @@ library by predefining macros that enable optional features:
         reduced one.
         The default is `NO`.
 
-    -DZ80_WITH_Q=(YES|NO)
-        Build the implementation of Q.
-        The default is `NO`.
-
-    -DZ80_WITH_RETX_NOTIFICATIONS_IN_IM0=(YES|NO)
+    -DZ80_WITH_IM0_RETX_NOTIFICATIONS=(YES|NO)
         Enable optional notifications for any `reti` or `retn` instruction
         executed during the interrupt mode 0 response.
         The default is `NO`.
 
+    -DZ80_WITH_Q=(YES|NO)
+        Build the implementation of Q.
+        The default is `NO`.
+
     -DZ80_WITH_SPECIAL_RESET=(YES|NO)
         Build the implementation of the special RESET.
         The default is `NO`.
@@ -300,6 +300,7 @@ the following macros:
 
     #define Z80_WITH_EXECUTE
     #define Z80_WITH_FULL_IM0
+    #define Z80_WITH_IM0_RETX_NOTIFICATIONS
     #define Z80_WITH_Q
     #define Z80_WITH_SPECIAL_RESET
     #define Z80_WITH_UNOFFICIAL_RETI
@@ -329,4 +330,4 @@ You should have received a copy of the GNU Lesser General Public License along
 with this library. If not, see <http://www.gnu.org/licenses/>.
 
 ________________________________________________________________________________
-Last update: 2022-02-12                                               README EOF
+Last update: 2023-02-14                                               README EOF

README.md

@@ -467,12 +467,12 @@ If in doubt, read the [CMake documentation](https://cmake.org/documentation/) fo
 	Build the full implementation of the interrupt mode 0 rather than the reduced one.  
 	The default is `NO`.
 
-* <span id="option_Z80_WITH_Q">**`-DZ80_WITH_Q=(YES|NO)`**</span>  
-	Build the implementation of [Q](https://worldofspectrum.org/forums/discussion/41704).  
+* <span id="option_Z80_WITH_IM0_RETX_NOTIFICATIONS">**`-DZ80_WITH_IM0_RETX_NOTIFICATIONS=(YES|NO)`**</span>  
+	Enable optional notifications for any `reti` or `retn` instruction executed during the interrupt mode 0 response.  
 	The default is `NO`.
 
-* <span id="option_Z80_WITH_RETX_NOTIFICATIONS_IN_IM0">**`-DZ80_WITH_RETX_NOTIFICATIONS_IN_IM0=(YES|NO)`**</span>  
-	Enable optional notifications for any `reti` or `retn` instruction executed during the interrupt mode 0 response.  
+* <span id="option_Z80_WITH_Q">**`-DZ80_WITH_Q=(YES|NO)`**</span>  
+	Build the implementation of [Q](https://worldofspectrum.org/forums/discussion/41704).  
 	The default is `NO`.
 
 * <span id="option_Z80_WITH_SPECIAL_RESET">**`-DZ80_WITH_SPECIAL_RESET=(YES|NO)`**</span>  
@@ -631,8 +631,8 @@ There are several macros that can be used to configure the source code of the li
 
 * **<code>#define [Z80_WITH_EXECUTE](#option_Z80_WITH_EXECUTE)</code>**
 * **<code>#define [Z80_WITH_FULL_IM0](#option_Z80_WITH_FULL_IM0)</code>**
+* **<code>#define [Z80_WITH_IM0_RETX_NOTIFICATIONS](#option_Z80_WITH_IM0_RETX_NOTIFICATIONS)</code>**
 * **<code>#define [Z80_WITH_Q](#option_Z80_WITH_Q)</code>**
-* **<code>#define [Z80_WITH_RETX_NOTIFICATIONS_IN_IM0](#option_Z80_WITH_RETX_NOTIFICATIONS_IN_IM0)</code>**
 * **<code>#define [Z80_WITH_SPECIAL_RESET](#option_Z80_WITH_SPECIAL_RESET)</code>**
 * **<code>#define [Z80_WITH_UNOFFICIAL_RETI](#option_Z80_WITH_UNOFFICIAL_RETI)</code>**
 * **<code>#define [Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG](#option_Z80_WITH_ZILOG_NMOS_LD_A_IR_BUG)</code>**

documentation/APIReference.rst

@@ -92,6 +92,7 @@ Configuration
 -------------
 
 .. doxygendefine:: Z80_OPTION_HALT_SKIP
+.. doxygendefine:: Z80_OPTION_IM0_RETX_NOTIFICATIONS
 .. doxygendefine:: Z80_OPTION_LD_A_IR_BUG
 .. doxygendefine:: Z80_OPTION_OUT_VC_255
 .. doxygendefine:: Z80_OPTION_XQ

documentation/Installation.rst

@@ -153,14 +153,14 @@ The second group of package-specific options configures the source code of the l
    Build the full implementation of the interrupt mode 0 rather than the reduced one. |br| |nl|
    The default is ``NO``.
 
-.. option:: -DZ80_WITH_Q=(YES|NO)
+.. option:: -DZ80_WITH_IM0_RETX_NOTIFICATIONS=(YES|NO)
 
-   Build the implementation of `Q <https://worldofspectrum.org/forums/discussion/41704>`_. |br| |nl|
+   Enable optional notifications for any ``reti`` or ``retn`` instruction executed during the interrupt mode 0 response. |br| |nl|
    The default is ``NO``.
 
-.. option:: -DZ80_WITH_RETX_NOTIFICATIONS_IN_IM0=(YES|NO)
+.. option:: -DZ80_WITH_Q=(YES|NO)
 
-   Enable optional notifications for any ``reti`` or ``retn`` instruction executed during the interrupt mode 0 response. |br| |nl|
+   Build the implementation of `Q <https://worldofspectrum.org/forums/discussion/41704>`_. |br| |nl|
    The default is ``NO``.
 
 .. option:: -DZ80_WITH_SPECIAL_RESET=(YES|NO)

documentation/Integration.rst

@@ -78,13 +78,13 @@ There are several macros that can be used to configure the source code of the li
 
    Enables the full implementation of the interrupt mode 0.
 
-.. c:macro:: Z80_WITH_Q
+.. c:macro:: Z80_WITH_IM0_RETX_NOTIFICATIONS
 
-   Enables the implementation of `Q <https://worldofspectrum.org/forums/discussion/41704>`_.
+   Enables optional notifications for any ``reti`` or ``retn`` instruction executed during the interrupt mode 0 response.
 
-.. c:macro:: Z80_WITH_RETX_NOTIFICATIONS_IN_IM0
+.. c:macro:: Z80_WITH_Q
 
-   Enables optional notifications for any ``reti`` or ``retn`` instruction executed during the interrupt mode 0 response.
+   Enables the implementation of `Q <https://worldofspectrum.org/forums/discussion/41704>`_.
 
 .. c:macro:: Z80_WITH_SPECIAL_RESET
 

sources/Z80.c

@@ -2031,9 +2031,12 @@ INSTRUCTION(hook)
 	static void im0_ld_r_a(IM0 const *self) {NOTIFY(ld_r_a);}
 
 
-#	ifdef Z80_WITH_RETX_NOTIFICATIONS_IN_IM0
+#	ifdef Z80_WITH_IM0_RETX_NOTIFICATIONS
 		#define IM0_NOTIFY_RETX(callback)		     \
-			if (self->callback != Z_NULL)		     \
+			if (	self->callback != Z_NULL &&	     \
+				(self->z80->options &		     \
+				Z80_OPTION_IM0_RETX_NOTIFICATIONS)   \
+			)					     \
 				{				     \
 				self->z80->data.uint8_array[2] |= 2; \
 				self->callback(CONTEXT);	     \

sources/Z80.pas

@@ -127,15 +127,17 @@ 	TZ80 = record
 	PZ80 = ^TZ80;
 
 const
-	Z80_OPTION_OUT_VC_255  = 1;
-	Z80_OPTION_LD_A_IR_BUG = 2;
-	Z80_OPTION_XQ          = 8;
-	Z80_OPTION_YQ          = 32;
-	Z80_OPTION_HALT_SKIP   = 64;
-	Z80_MODEL_ZILOG_NMOS   = (Z80_OPTION_LD_A_IR_BUG or Z80_OPTION_XQ or Z80_OPTION_YQ);
-	Z80_MODEL_ZILOG_CMOS   = (Z80_OPTION_OUT_VC_255 or Z80_OPTION_XQ or Z80_OPTION_YQ);
-	Z80_MODEL_NEC_NMOS     = Z80_OPTION_LD_A_IR_BUG;
-	Z80_MODEL_ST_CMOS      = (Z80_OPTION_OUT_VC_255 or Z80_OPTION_LD_A_IR_BUG or Z80_OPTION_YQ);
+	Z80_OPTION_OUT_VC_255             = 1;
+	Z80_OPTION_LD_A_IR_BUG            = 2;
+	Z80_OPTION_HALT_SKIP              = 4;
+	Z80_OPTION_XQ                     = 8;
+	Z80_OPTION_IM0_RETX_NOTIFICATIONS = 16;
+	Z80_OPTION_YQ                     = 32;
+
+	Z80_MODEL_ZILOG_NMOS = (Z80_OPTION_LD_A_IR_BUG or Z80_OPTION_XQ or Z80_OPTION_YQ);
+	Z80_MODEL_ZILOG_CMOS = (Z80_OPTION_OUT_VC_255 or Z80_OPTION_XQ or Z80_OPTION_YQ);
+	Z80_MODEL_NEC_NMOS   = Z80_OPTION_LD_A_IR_BUG;
+	Z80_MODEL_ST_CMOS    = (Z80_OPTION_OUT_VC_255 or Z80_OPTION_LD_A_IR_BUG or Z80_OPTION_YQ);
 
 	Z80_REQUEST_REJECT_NMI    = 2;
 	Z80_REQUEST_NMI           = 4;