Clarifications to the explanation of interrupts (#417)

* Highlight instructions more consistently

* Clarify the explanation of interrupts

Co-authored-by: Antonio Vivace <[email protected]>
Co-authored-by: Eldred Habert <[email protected]>

Author: 3 people

src/Interrupts.md

@@ -16,14 +16,14 @@ the following instructions/events only:
 EI     ; Enables interrupts  (that is, IME=1)
 DI     ; Disables interrupts (that is, IME=0)
 RETI   ; Enables interrupts and returns (same as the instruction sequence EI, RET)
-<INT>  ; Disables interrupts and calls interrupt vector
+<ISR>  ; Disables interrupts and calls the interrupt handler
 ```
 
-Where \<INT\> means the operation which is automatically executed by the
-CPU when it executes an interrupt.
+Where \<ISR\> is the Interrupt Service Routine that is automatically executed
+by the CPU when it services an interrupt request.
 
 The effect of `ei` is delayed by one instruction. This means that `ei`
-followed immediately by DI does not allow any interrupts between them.
+followed immediately by `di` does not allow any interrupts between them.
 This interacts with the [`halt` bug](<#halt bug>) in an interesting way.
 
 ## FFFF - IE - Interrupt Enable (R/W)
@@ -46,61 +46,59 @@ Bit 3: Serial   Interrupt Request (INT $58)  (1=Request)
 Bit 4: Joypad   Interrupt Request (INT $60)  (1=Request)
 ```
 
-When an interrupt signal changes from low to high, the
-corresponding bit in the IF register becomes set. For example, Bit 0
+When an interrupt request signal changes from low to high, the
+corresponding bit in the IF register is set. For example, Bit 0
 becomes set when the LCD controller enters the VBlank period.
 
-Any set bits in the IF register are only **requesting** an interrupt to be
-executed. The actual **execution** happens only if both the IME flag and
-the corresponding bit in the IE register are set, otherwise the
-interrupt "waits" until both IME and IE allow its execution.
+Any set bits in the IF register are only **requesting** an interrupt.
+The actual **execution** of the interrupt handler happens only if both the IME flag and
+the corresponding bit in the IE register are set; otherwise the
+interrupt "waits" until both IME and IE allow it to be serviced.
 
 Since the CPU automatically sets and clears the bits in the IF register, it
-is usually not required to write to the IF register. However, the user
+is usually not necessary to write to the IF register. However, the user
 may still do that in order to manually request (or discard) interrupts.
-Like with real interrupts, a manually requested interrupt isn't executed
-unless/until IME and IE allow its execution.
+Just like real interrupts, a manually requested interrupt isn't serviced
+unless/until IME and IE allow it.
 
 ## Interrupt Handling
 
 1. The IF bit corresponding to this interrupt and the IME flag are reset by the CPU.
 The former "acknowledges" the interrupt, while the latter prevents any further interrupts
 from being handled until the program re-enables them, typically by using the `reti` instruction.
 2. The corresponding interrupt handler (see the IE and IF register descriptions [above](<#FFFF - IE - Interrupt Enable (R/W)>)) is
-called by the CPU. This is a regular call, exactly like what would be performed by a `call <vector>` instruction (the current PC is pushed on the stack
-and then set to the address of the interrupt vector).
+called by the CPU. This is a regular call, exactly like what would be performed by a `call <address>` instruction (the current PC is pushed onto the stack
+and then set to the address of the interrupt handler).
 
-The following occurs when control is being transferred to an interrupt handler:
+The following interrupt service routine is executed when control is being transferred to an interrupt handler:
 
-1. Two wait states are executed (2 M-cycles pass while nothing
-occurs, presumably the CPU is executing `nop`s during this time).
-2. The current PC is pushed to the stack, consuming 2 more M-cycles.
-3. The PC register is set to the address of the handler ($40, $48, $50, $58, $60).
+1. Two wait states are executed (2 M-cycles pass while nothing happens; presumably the CPU is executing `nop`s during this time).
+2. The current value of the PC register is pushed onto the stack, consuming 2 more M-cycles.
+3. The PC register is set to the address of the handler (one of: $40, $48, $50, $58, $60).
 This consumes one last M-cycle.
 
-The entire ISR **should** last a total of 5 M-cycles.
+The entire routine **should** last a total of 5 M-cycles.
 This has yet to be tested, but is what the Z80 datasheet implies.
 
 ## Interrupt Priorities
 
-In the following three situations it might happen that more than one bit in the IF register is set, requesting more than one interrupt at once:
+In the following circumstances it is possible that more than one bit in the IF register is set, requesting more than one interrupt at once:
 
-1. More than one interrupt signal changed from Low to High at the same time.
-2. Several interrupts have been requested while IME/IE didn't allow them to be handled directly.
+1. More than one interrupt request signal changed from low to high at the same time.
+2. Several interrupts have been requested while IME/IE didn't allow them to be serviced.
 3. The user has written a value with several bits set (for example binary 00011111) to the IF register.
 
-If IME and IE allow the execution of more than one of the
+If IME and IE allow the servicing of more than one of the
 requested interrupts, the interrupt with the highest priority
-is executed first. The priorities follow the same order as the bits in the IE
+is serviced first. The priorities follow the order of the bits in the IE
 and IF registers: Bit 0 (VBlank) has the highest priority, and Bit 4
 (Joypad) has the lowest priority.
 
 ## Nested Interrupts
 
 The CPU automatically disables all the other interrupts by setting IME=0
-when it executes an interrupt. Usually IME remains zero until the
-interrupt handler returns (and sets IME=1 by means of the RETI instruction).
-However, if you want any other interrupts (of any priority)
-to be allowed to be executed from inside the interrupt
-handler, then you can use the EI instruction in the interrupt
-handler.
+when it services an interrupt. Usually IME remains zero until the
+interrupt handler returns (and sets IME=1 by means of the `reti` instruction).
+However, if you want to allow the servicing of other interrupts (of any priority)
+during the execution of an interrupt handler, you may do so by using the
+`ei` instruction in the handler.

src/Memory_Map.md

@@ -25,8 +25,8 @@ The following addresses are supposed to be used as jump vectors:
 -   Interrupts: 0040, 0048, 0050, 0058, 0060
 
 However, this memory area (0000-00FF) may be used for any other purpose in case that your
-program doesn't use any (or only some) RST instructions or interrupts. RST
-is a 1-byte instruction that works similarly to the 3-byte CALL instruction, except
+program doesn't use any (or only some) [`rst`](https://rgbds.gbdev.io/docs/v0.5.2/gbz80.7/#RST_vec) instructions or interrupts. `rst`
+is a 1-byte instruction that works similarly to the 3-byte `call` instruction, except
 that the destination address is restricted. Since it is 1-byte sized,
 it is also slightly faster.