Source code comments.

Author: redcode

sources/Z80.c

@@ -2626,18 +2626,17 @@ Z80_API zusize z80_run(Z80 *self, zusize cycles)
 						FLAGS = F & ~(zuint8)PF;
 #				endif
 
-				/*---------------------------------------------------------------------.
-				| The INT acknowledge cycle (INTA) indicates that the interrupting I/O |
-				| device can write to the data bus. 2 wait T-states are automatically  |
-				| added to this M-cycle, allowing sufficient time to identify which    |
-				| device must insert the interrupt response data (IRD). The first and  |
-				| possibly sole byte of the IRD is read from the data bus during this  |
-				| special M1 cycle.						       |
-				|								       |
-				| The value FFh is assumed when the `Z80::inta` callback is not used.  |
-				| This is the most convenient default IRD, since an `rst 38h` will be  |
-				| executed if the interrupt mode is 0.				       |
-				'=====================================================================*/
+				/*-----------------------------------------------------------------------.
+				| The INT acknowledge M-cycle (INTA) indicates that the interrupting I/O |
+				| device can write to the data bus. The CPU adds 2 wait T-states to this |
+				| M-cycle, allowing sufficient time to identify which device must insert |
+				| the interrupt response data (IRD). The first and possibly sole byte of |
+				| the IRD is read from the data bus during this special M1 cycle.	 |
+				|									 |
+				| The value FFh is assumed when the `Z80::inta` callback is not used.	 |
+				| This is the most convenient default IRD, since an `rst 38h` will be	 |
+				| executed if the interrupt mode is 0.					 |
+				'=======================================================================*/
 				R++;
 				ird = (self->inta != Z_NULL) ? self->inta(CONTEXT, PC) : 0xFF;
 
@@ -2651,15 +2650,15 @@ Z80_API zusize z80_run(Z80 *self, zusize cycles)
 					| Interrupt Mode 0: Execute Instruction	     | T-states: 2*n + instruction |
 					|--------------------------------------------------------------------------|
 					| An instruction supplied via the data bus is executed. Its first byte is  |
-					| read during the INT acknowledge cycle (INTA). If it is an opcode prefix, |
-					| additional M-cycles of this kind are produced until the final opcode of  |
-					| the instruction is fetched [1]. Each INTA M-cycle takes as many T-states |
-					| as its normal M1 counterpart (the opcode fetch M-cycle) plus the 2 wait  |
-					| T-states mentioned above [1]. Subsequent bytes of the instruction are	   |
-					| fetched by using normal memory read M-cycles [1, 2], during which the	   |
-					| interrupting I/O device must still supply the data [2]. The PC register, |
-					| however, remains at its pre-interrupt state, not being incremented as a  |
-					| result of the instruction fetch [1, 2].				   |
+					| read during the INTA M-cycle and, if it is an opcode prefix, additional  |
+					| M-cycles of this kind are produced until the final opcode of the	   |
+					| instruction is fetched [1]. Each INTA M-cycle takes as many T-states as  |
+					| its normal M1 counterpart (the opcode fetch M-cycle) plus the 2 wait	   |
+					| T-states mentioned in the previous comment [1]. Subsequent bytes of the  |
+					| instruction are fetched by using normal memory read M-cycles [1, 2],	   |
+					| during which the interrupting I/O device must still supply the data [2]. |
+					| The PC register, however, remains at its pre-interrupt state, not being  |
+					| incremented as a result of the instruction fetch [1, 2].		   |
 					|									   |
 					| References:								   |
 					| 1. Checked with "Visual Z80 Remix".					   |
@@ -2901,9 +2900,9 @@ Z80_API zusize z80_run(Z80 *self, zusize cycles)
 					| of the interrupt response vector "must be a zero", since the address |
 					| formed "is used to get two adjacent bytes to form a complete 16-bit  |
 					| service routine starting address and the addresses must always start |
-					| in even locations" [1]. However, Sean Young's experiments confirmed  |
-					| that there is no such limitation [2]; any vector works regardless of |
-					| whether it is even or odd.					       |
+					| in even locations" [1]. However, Sean Young's confirmed that there   |
+					| is no such limitation [2]; the CPU fetches the ISR pointer from the  |
+					| specified location regardless of the value of bit 0 of the IRD.      |
 					|								       |
 					| References:							       |
 					| 1. Zilog (2005-03). "Z80 CPU User Manual" rev. 5, pp. 25-26.	       |

sources/step-test-Z80.c

@@ -37,12 +37,26 @@
 /* MARK: - Types */
 
 typedef struct {
+	/* Title of the member as shown in the mismatch reports. */
 	char const *caption;
+
+	/* Key of the member as shown in the JSON files. */
 	char const *key;
+
+	/* Offset of the member within the Z80 structure. */
 	zusize offset;
+
+	/* Maximum value the member can hold. */
 	zuint16 maximum_value;
 } Member;
 
+/*-----------------------------------------------------------------------------.
+| `Cycle` and `Port` store information about a clock cycle and an I/O port     |
+| operation, respectively. They are packed to avoid any padding bytes, so that |
+| the actual results can be compared directly with the expected ones read from |
+| the JSON test files.							       |
+'=============================================================================*/
+
 typedef Z_PACKED_STRUCTURE_BEGIN {
 	zuint16 address;
 	zsint16 value;
@@ -109,6 +123,12 @@ static char const *field_separator = "";
 static zbool cpu_break;
 
 
+/*----------------------------------------------------------------------------.
+| `add_cycle` and `add_port` add entries to the lists of recorded cycles and  |
+| I/O port operations, respectively. If memory reallocation fails, they break |
+| the CPU emulation and ignore further entries.				      |
+'============================================================================*/
+
 static void add_cycle(zuint16 address, zsint16 value, char const *pins)
 	{
 	Cycle *c;
@@ -121,6 +141,7 @@ static void add_cycle(zuint16 address, zsint16 value, char const *pins)
 		if ((c = realloc(cycles, cycles_size * sizeof(Cycle))) == Z_NULL)
 			{
 			z80_break(&cpu);
+			cpu_break = Z_TRUE;
 			return;
 			}
 
@@ -164,7 +185,7 @@ static void add_port(zuint16 port, zuint8 value, char direction)
 	}
 
 
-/* MARK: - Callbacks */
+/* MARK: - CPU Callbacks */
 
 static zuint8 cpu_fetch_opcode(void *context, zuint16 address)
 	{
@@ -278,13 +299,16 @@ static zbool validate_test_state(cJSON *state)
 	cJSON *item, *subitem;
 	Member const *member;
 
+	/* The state object must contain all CPU members plus the `"ram"` array. */
 	if (	!cJSON_IsObject(state)							||
 		cJSON_GetArraySize(state) != (int)Z_ARRAY_SIZE(members) + /* "ram" */ 1 ||
 		(item = cJSON_GetObjectItem(state, "ram")) == Z_NULL			||
 		!cJSON_IsArray(item)
 	)
 		return Z_FALSE;
 
+	/* The `"ram"` array must contain arrays of two numbers: 16-bit address and
+	   8-bit value. */
 	cJSON_ArrayForEach(subitem, item) if (
 		!cJSON_IsArray(subitem)							||
 		cJSON_GetArraySize(subitem) != 2					||
@@ -293,14 +317,20 @@ static zbool validate_test_state(cJSON *state)
 	)
 		return Z_FALSE;
 
+	/* Each CPU member must be present and hold a valid number according to its type. */
 	for (member = members; member != members + Z_ARRAY_SIZE(members) - 2; member++)
 		if (	(item = cJSON_GetObjectItem(state, member->key)) == Z_NULL ||
 			!is_number_between(item, 0, member->maximum_value)
 		)
 			return Z_FALSE;
 
 	return Z_TRUE;
-/*	return	2.0 !=
+
+	/*-------------------------------------------------------------.
+	| EI and P are mutually exclusive, as the previous instruction |
+	| cannot be `ei` and `ld a,{i|r}` at the same time.	       |
+	'=============================================================
+	return	2.0 !=
 		cJSON_GetNumberValue(cJSON_GetObjectItem(state, "ei")) +
 		cJSON_GetNumberValue(cJSON_GetObjectItem(state, "p" ));*/
 	}