@nataliapc/mcp-openmsx 1.1.15 → 1.2.3

package/resources/programming/asm_fast_loops.md

@@ -0,0 +1,200 @@
+# Z80 programming techniques - Loops
+
+Here I will discuss two methods to drastically increase the execution speed of different kinds of loops in assembly.
+
+- [Fast 16-bit loops](#fast-16-bit-loops)
+  - [Variable length loops](#variable-length-loops)
+- [Unrolling OTIRs and such](#unrolling-otirs-and-such)
+  - [Making LDIR 21% faster](#making-ldir-21-faster)
+
+## Fast 16-bit loops
+
+Often 16-bit loops are done like this:
+
+```assembler
+    ld de,nnnn
+Loop:
+    ; ... do something here
+    dec de
+    ld a,d
+    or e
+    jp nz,Loop
+```
+
+Here DE counts down and D and E are OR-ed to check if the loop has completed. However there’s a much faster way to loop. In fact, looping with 16 bit counters can be as fast as with 8 bit counters. Surprised? Let me explain.
+
+When you use a standard Z80 8-bit loop command like DJNZ, or OTIR, etc. the value of B is decreased until it reaches 0. If you want to loop 256 times, you can set the value of B to 0. So what happens if you loop 24 times, and then loop again? You’ll have looped 280 times!
+
+This is the core of the technique. Given a 16-bit number with an MSB (the higher 8 bits) and an LSB (the lower 8 bits), you start off by looping the amount of times given by the LSB, and when B reaches 0 you do it again MSB times, each of which will loop it 256 more times. An example:
+
+```assembler
+    ld b,10         ; The LSB of the loop is 10
+    ld d,3          ; The MSB of the loop + the first loop is 3
+Loop:
+    ; ... do something here
+    djnz Loop
+    dec d
+    jp nz,Loop
+```
+
+This will loop 522 times (50AH).
+
+Now the real story is a little more complex than described above. As you can see the outer loop counter is the MSB + 1. However this is not always the case. Consider this: to loop 511 times (1FFH) you have to use B = 255 and D = 2, one loop of 255 iterations and then another of 256. However to loop 512 times (200H) you have to use B = 0, but D = 2 still! In general, the rule is as follows: B is the LSB, and D is the MSB increased by 1 unless B equals zero. Without this exception for a zero LSB, you will loop 256 times too often.
+
+Let’s compare the speed of this loop with a ‘common’ 16-bit loop. Speed on the Z80 is measured in T-states, also known as clock ticks or cycles. For an overview of T-states for each instruction, check the “Timing Z80+M1” column in the instruction set overview.
+
+The common loop in the first example uses 4 instructions to loop, which add up to a total of 28 T-states per iteration. Looking at the fast loop however, the inner loop uses only a DJNZ instruction which takes 14 T-states, just like a normal 8-bit loop. Once every 256 iterations it also executes the outer loop which takes a little longer but still less than the common loop: 25 T-states. Because the outer loop is executed so infrequently, its cost is negligible and overall we can say the fast loop is twice as fast as the common one.
+
+The biggest downside of the fast loop is that it is no longer easy to see at a glance how many iterations the loop performs. You should probably add a comment next to the counter values to mention the total number of loops.
+
+### Variable length loops
+
+If you want to have fast loops with a variable counter value, you can calculate the correct values for B and D. This could be done using a conditional increase of the MSB, however that requires a compare and a jump which isn’t the fastest way to do go about it. In stead, you can use the following calculation which takes the counter value in DE and puts the resulting separated counters in D and B:
+
+```assembler
+    ld b,e          ; Mystery fast loop calculus
+    dec de
+    inc d
+```
+
+That’ll take just 17 T-states to precalculate the values, and compared to the slow 16-bit loop you’ll regain those after a loop or two.
+
+So, to summarize, a full-fledged fast 16-bit loop looks like this:
+
+```assembler
+    ld b,e          ; Number of loops is in DE
+    dec de          ; Calculate DB value (destroys B, D and E)
+    inc d
+Loop:
+    ; ... do something here
+    djnz Loop
+    dec d
+    jp nz,Loop
+```
+
+## Unrolling OTIRs and such
+
+When you want to send a block from your memory to a certain port, you can use the OTIR instruction. With this instruction you can specify the number of bytes to output. This is for example used in routines which execute VDP commands, where the part which sends the command usually looks like this:
+
+```assembler
+    ld hl,command   ; the address where the VDP command is stored
+    ld c,9BH        ; the VDP port to write to
+    ld b,15         ; the number of loops (yes, ld bc,0F9BH is faster)
+    otir
+```
+
+However, if you know in advance how many loops the otir will go through, and if you don’t care too much about wasting a little space, you can also use the OUTI instruction instead of the OTIR instruction. OUTI doesn’t loop automatically, but it does its work in 18 T-states, 5 cycles faster than OTIR which needs 23 T-states per loop. So if you just unroll the OTIR in the example above using 15 OUTIs, it saves you 5 T-states per loop (except for the last one). That adds up to a grand total of 70 T-states out of 340, about 21% faster. Here’s how that looks:
+
+```assembler
+    ld hl,command
+    ld c,9BH
+    outi            ; 15x OUTI
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+    outi
+```
+
+To make this look a little more compact, many assemblers supports a repeat directive, something like:
+
+```assembler
+    REPEAT 15
+    outi
+    ENDR
+```
+
+Check your assembler’s manual for the precise syntax, it varies and as such this directive is not portable across assemblers.
+
+See this article for a more complete example to execute VDP commands.
+
+### Making LDIR 21% faster
+
+Now, on with the lesson. Aside from OTIR you can also unroll other things. INIR, LDIR and LDDR will also greatly benefit from this method, and sometimes it is also beneficial to unroll normal loops which use DJNZ, JR or JP.
+
+In the case of LDIR however, the number of loops is often too large to simply use an LDI that number of times. That would take up too much space. So what we can do instead is to unroll only part of the loop. Say, we need to LDIR something 256 (100H) times. Instead of LDIR we could write:
+
+```assembler
+    ld bc,256
+Loop:
+    ldi  ; 16x LDI
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    jp pe,Loop  ; Loop until bc = zero
+```
+
+This method is almost 19% faster than an LDIR. Quit a significant performance gain! Note that LDI sets the parity flag to even as long as BC != 0. The jump at the end adds a little extra overhead, you can increase the number of LDIs to gain an additional few percents of speed up to almost 22%, however 16 is a nice compromise between speed and code size.
+
+However, as you might already have noticed, this will only work if the number of loops is a multiple of 16. If it’s not, BC will never be 0 at the end of a series of 16 LDIs and we’ll end up in an endless loop followed by a reset or crash because eventually it’ll overwrite itself or system memory. That’s not what we want. If the number of loops is known in advance, it’s easiest to just put some additional LDIs before the loop.
+
+However if the number of loops is unknown, or you simply want a faster but generic alternative for LDIR, you could try and detect when the last loop is started, and in that case let a ‘normal’ LDIR handle the last few loops. Well, that isn’t too hard, it can be handled using a few compares.
+
+A faster and slightly trickier method is to jump inside the series of LDIs based on the count modulo the number of unrolled instructions. This is put into practice in the following example:
+
+```assembler
+;
+; Up to 19% faster alternative for large LDIRs (break-even at 21 loops)
+; hl = source (“home location”)
+; de = destination
+; bc = byte count
+;
+FastLDIR:
+    xor a
+    sub c
+    and 16 - 1
+    add a,a
+    di
+    ld (FastLDIR_jumpOffset),a
+    ei
+    jr nz,$  ; self modifying code
+FastLDIR_jumpOffset: equ $ - 1
+FastLDIR_Loop:
+    ldi  ; 16x LDI
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    ldi
+    jp pe,FastLDIR_Loop
+    ret
+```
+
+It first calculates the number of loops modulo the LDI series size, then uses a self modifying relative jump to start at the appropriate position in the LDI series. The set-up does add some overhead, the break-even point compared to a normal OTIR is at 21 loops. Over a large number of iterations the performance gain is 19%, quite a lot I think so I hope it’ll be of some use.
+
+~Grauw
+
+## Source
+
+https://map.grauw.nl/articles/fast_loops.php

package/resources/programming/asm_getslot.md

@@ -0,0 +1,143 @@
+# GETSLT: Get slot ID of any page
+
+The BIOS slot routines RDSLT, ENASLT, etc. all take a slot ID. Sometimes you construct this yourself, but often you need to know the slot ID of a page that was already selected before. The initialisation code of ROM cartridges for example typically wants to enable the slot of page 1 in page 2 as well.
+
+You can determine the slot ID of a currently paged address with a GETSLT routine. There is no BIOS routine for this, but the process is described in the MSX2 Technical Handbook and several other references, along with code examples.
+
+This is an assembly implementation which works for all pages (followed by an explanation):
+
+```assembly
+RSLREG: equ 138H
+EXPTBL: equ 0FCC1H
+SLTTBL: equ 0FCC5H
+
+; h = memory address high byte (bits 6-7: page)
+; a <- slot ID formatted F000SSPP
+; Modifies: f, bc, de
+Memory_GetSlot:
+    call RSLREG
+    bit 7,h
+    jr z,PrimaryShiftContinue
+    rrca
+    rrca
+    rrca
+    rrca
+PrimaryShiftContinue:
+    bit 6,h
+    jr z,PrimaryShiftDone
+    rrca
+    rrca
+PrimaryShiftDone:
+    and 00000011B
+    ld c,a
+    ld b,0
+    ex de,hl
+    ld hl,EXPTBL
+    add hl,bc
+    ex de,hl
+    ld a,(de)
+    and 80H
+    or c
+    ret p
+    ld c,a
+    inc de  ; move to SLTTBL
+    inc de
+    inc de
+    inc de
+    ld a,(de)
+    bit 7,h
+    jr z,SecondaryShiftContinue
+    rrca
+    rrca
+    rrca
+    rrca
+SecondaryShiftContinue:
+    bit 6,h
+    jr nz,SecondaryShiftDone
+    rlca
+    rlca
+SecondaryShiftDone:
+    and 00001100B
+    or c
+    ret
+```
+
+## Explanation
+
+The MSX slot selection system divides the 64K CPU memory address space into 4 pages, from page 0 (0000H-3FFFH) to page 3 (C000H-FFFFH). In each of these pages you can select a different slot. Some of these slots are internal, others are for the external cartridge slots. The BIOS routines idenfity a slot with a slot ID, using the bit-format FxxxSSPP. The two P bits indicate the primary slot, the F bit indicates whether the primary slot is expanded, and if so the S bits indicate the secondary slot.
+
+```assembly
+; h = memory address high byte (bits 6-7: page)
+; a <- slot ID formatted F000SSPP
+; Modifies: f, bc, de
+Memory_GetSlot:
+    call RSLREG
+    bit 7,h
+    jr z,PrimaryShiftContinue
+    rrca
+    rrca
+    rrca
+    rrca
+PrimaryShiftContinue:
+    bit 6,h
+    jr z,PrimaryShiftDone
+    rrca
+    rrca
+PrimaryShiftDone:
+    and 00000011B
+```
+
+This first part determines the value for the primary slot number (PP bits) by reading the primary slot register through the RSLREG BIOS routine. The returned byte has two bits to indicate the primary slot for each of the pages, in the bit-format 33221100. Because the slot ID specifies the primary slot number (PP) in bits 0-1, we shift until the appropriate bits are in the correct position.
+
+Note that if you need a shorter version hardcoded for a specific page, you can eliminate the conditional code here.
+
+```assembly
+    ld c,a
+    ld b,0
+    ex de,hl
+    ld hl,EXPTBL
+    add hl,bc
+    ex de,hl
+    ld a,(de)
+    and 80H
+    or c
+    ret p
+```
+
+In this second part we determine the value for the expanded flag (F bit) by inspecting the EXPTBL table in system memory. This table consists of 4 bytes, one for each slot, where bit 7 indicates whether the slot is expanded. Because in rare cases bits 0-6 can contain a non-zero value, we and the value with 80H to mask out the unwanted bits before we insert it into the slot ID. If the slot is not expanded, we stop here.
+
+```assembly
+    ld c,a
+    inc de  ; move to SLTTBL
+    inc de
+    inc de
+    inc de
+    ld a,(de)
+    bit 7,h
+    jr z,SecondaryShiftContinue
+    rrca
+    rrca
+    rrca
+    rrca
+SecondaryShiftContinue:
+    bit 6,h
+    jr nz,SecondaryShiftDone
+    rlca
+    rlca
+SecondaryShiftDone:
+    and 00001100B
+    or c
+    ret
+```
+
+Lastly we determine the value for the secondary slot number (SS bits). Instead of reading from the secondary slot registers directly, which is a rather complicated affair, we advance the pointer to the SLTTBL table, which is a mirror of the four secondary slot registers. These have two bits to indicate the secondary slot for each memory page, in the same bit-format 33221100 as the primary slot register. Because the slot ID specifies the secondary slot number (SS) in bits 2-3, we shift until the appropriate bits are in the correct position.
+
+Again note that if you need a shorter version hardcoded for a specific page, you can eliminate the conditional code here.
+
+Now we have fully determined the slot ID for a page.
+
+~~Grauw
+
+## Source
+
+https://map.grauw.nl/sources/getslot.php

package/resources/programming/asm_interrupts.md

@@ -0,0 +1,202 @@
+# Interrupts
+
+Many machine language programmers will have written a program that needed to be called from the interrupt routine. Sometimes such a program does not work well, or at all, for some vague reason. Time to shine some light on those shady interrupts.
+
+Author: Ramon van der Winkel  
+Published in: MSX Computer Magazine 51 / MemMan TDK  
+Translated by: Laurens Holst
+
+To extend the BIOS interrupt routine, the extension has to be attached to one of the two interrupt hooks. A choice has to be made between the hooks H.KEYI and H.TIMI. Both are invoked by the interrupt routine, however there are differences.
+
+The H.KEYI hook is invoked every interrupt, while the H.TIMI hook is invoked at regular intervals. 50 or 60 times per second, to be precise. For example, a background song should be attached to H.TIMI, because the playback speed has to be regular.
+
+An interrupt is — simply put — a notification from a device to the processor. With an interrupt the device tells the processor to take action. A modem can use an interrupt to notify the processor that a character has been received. Because a program that fetches the character from the modem has to be invoked every interrupt, it should be attached to H.KEYI.
+
+## Set-up
+
+Interrupt routines have to be written such that they can be invoked at every possible moment. They can not change anything that would negatively impact the functioning of the main program. All register values must be preserved for example, otherwise the main program could yield some very strange results if an interrupt routine would just change the contents of a couple of registers. Also they need to account for the current state of the primary and secondary slot registers and possibly the memory mapper setting.
+
+The preservation of the register values is done by the interrupt handler in the BIOS. A program which is attached to these hooks does not need to preserve them as well. There is one exception to this: programs who attach themselves to the H.TIMI hook must preserve register A. This register is a copy of VDP status register S#0, which is read by the BIOS routine before H.TIMI is invoked. After the hook returns the BIOS uses the contents of this register.
+
+One of the devices that generate interrupts in the MSX is the video processor. It generates and interrupt at the moment the last line of the active area of the screen — where the text and graphics can appear — is displayed. Because this happens 50 times per second, this means that each second there are 50 interrupts coming from the VDP. If the VDP is set to 60Hz, the interrupts will also be generated 60 times per second.
+
+## Handling
+
+The BIOS interrupt routine first invokes the H.KEYI hook. Next it checks whether the interrupt originates from the VDP. If not, the interrupt routine ends, otherwise the second part of the routine is executed.
+
+This part invokes the H.TIMI hook and then performs a couple of standard activities, such as reading the keyboard, executing Basic’s ON INTERVAL GOSUB and ON STRIG GOSUB instructions, incrementing the Basic variable TIME, handling the PLAY statement, et cetera. See the overview that accompanies this article for more details about what tasks the interrupt routing performs exactly.
+
+To determine whether an interrupt originates from the VDP, it looks at the contents of the afore mentioned VDP register S#0. Bit 7 of this register is set by the VDP the moment the last line of the screen has been displayed and the interrupt is generated. After the register is read, the bit is automatically reset to 0. While this bit is 1 the VDP will not generate new interrupts. At every VDP interrupt this bit needs to be read, otherwise the VDP will not generate any new interrupts.
+
+When the H.TIMI hook is invoked, register A will contain the value of VDP register S#0 that was just read. After the hook returns this will be stored in the system variable STATFL. For this reason the contents of register A need to be preserved by programs that attach themselves to the H.TIMI hook.
+
+### Global overview of the tasks performed by the MSX BIOS interrupt routine
+
+#### Always
+- Stack all registers
+- Invoke H.KEYI hook
+- Read VDP status register S#0
+- Turbo R: Check PAUSE key
+- Check VDP interrupt
+
+#### At VDP interrupt
+- Invoke H.TIMI hook
+- Enable Interrupts (EI)
+- Save S#0 in STATFL
+- ON INTERVAL GOSUB
+- Increase TIME variable (JIFFY)
+- Handle PLAY
+
+#### Every second VDP interrupt
+- Keyboard scan
+- Processing keys
+- ON STRIG GOSUB
+- Key repetition
+
+#### Always
+- Restore all registers
+- Enable Interrupts (EI)
+- RETurn from Interrupt (RETI)
+
+## Types
+
+The Z80 processor — and of course the compatible R800 — has three ways to handle interrupts, of which only two are really used on the MSX. These ways are called Interrupt Modes. They are numbered 0 through 2. The interrupt mode can be selected using one of the machine language instructions IM 0, IM 1 or IM 2.
+
+IM 0 is not used on the MSX system. In this mode a device can provide the CPU with an instruction to execute. The most used interrupt mode on MSX is IM 1. In this mode the processor always calls a fixed address: 0038h. At this address every MSX BIOS has a jump to the interrupt routine.
+
+The other interrupt mode in use is IM 2, on the MSX it is used by CP/M. In this mode the address that is called is determined by combining the I register and a byte from the device. The I register can be set by the program and contains the high part of the address. The low part is provided by the device. The combined address isn’t the address of the interrupt routine yet, but it specifies a memory location that contains the routine’s start address. Because the routine’s address always has to be in an even memory location, 128 different interrupt routines can be called. The device determines which.
+
+In CP/M all 128 possible memory addresses are filled with the same value, so that all interrupts will end up at the same routine. Just to be sure, CP/M’s authors also had the interrupt routine start at an address where the high and low parts of the address are identical. In case an interrupt would occur where the device provides a value with bit 0 set, it will still end up at the correct address. An address with bit 0 set can occur if the device does not provide a specific value at all, because it expects interrupt mode 1 to be active.
+
+The program can inhibit interrupts, preventing them from occurring. To do so the program needs to tell the CPU that interrupts generated by devices should not be handled. The CPU has two flags for this, named IFF1 and IFF2. IFF is an abbreviation of Interrupt Flip Flop. When the CPU detects an interrupt, it first checks IFF1. If this flag is set the interrupt is handled, otherwise it is ignored.
+
+The machine language instructions to influence these flags are Disable Interrupts (DI) and Enable Interrupts (EI). A DI instruction will clear both flags and cause the CPU to ignore interrupts. After an EI instruction the flags will be set and interrupts will be accepted again.
+
+Besides the above mentioned interrupts there is also a type of interrupt which can not be ignored by the CPU. This is the so-called Non Maskable Interrupt or NMI. An NMI is processed similar to an interrupt in interrupt mode 1, however in this case the CPU will call address 0066h. Even though these interrupts do not normally occur on MSX computers, the MSX BIOS does have a NMI interrupt handling routine at that address.
+
+MSX-DOS only provides a handler for ‘normal’ interrupts. This routine enables the BIOS in page 0 and invokes its interrupt routine. Afterwards it re-enables RAM in page 0. Non Maskable Interrupts can not occur in MSX-DOS because there is no handling routine for it. Address 0066h is right in the middle of MSX-DOS’s first FCB — File Control Block — buffer, which starts at address 005Ch.
+
+|Address|Description|
+|:-:|:--|
+|FD9Ah|H.KEYI hook|
+|FD9Fh|H.TIMI hook|
+|FDD6h|H.NMI hook|
+|F3E7h|STATFL variable|
+|FC9Eh|JIFFY variable|
+|0038h|IM 1 interrupts entry point|
+|0066h|NMI interrupts entry point|
+
+## The call
+
+Before the interrupt routine is executed, the program counter is saved to the stack. After the interrupt routine ends this address is retrieved and the main program continues. In other words, the interrupt routine is executed as if the main program executes a CALL to a subroutine, in this case the interrupt routine.
+
+To prevent nesting the CPU automatically resets the IFF1 and IFF2 flags (DI). Before calling an NMI routine IFF1 is copied into IFF2 and only IFF1 is reset, so that the state of IFF1 can be restored at the end of the NMI routine.
+
+Just like normal routines, interrupt routines can be terminated with a RET instruction. However, the CPU has two special instructions to end interrupt routines: RETurn from Interrupt (RETI) and RETurn from Non maskable interrupt (RETN).
+
+The RETI instruction can be recognised by a device at the moment it is executed by the CPU, so that it can know that its interrupt has been handled. For this reason it’s better to use a RETI than a RET, although they are identical in function. Note that IFF1 is not set by the RETI instruction. This must be done with an EI instruction in the interrupt routine.
+
+The RETN instruction at the end of an NMI-routine however **is needed** to restore IFF1. RETN copies the state of IFF2 into IFF1, so that it is restored to the value it had before the NMI occurred. Apart from this a RETN instruction behaves like a normal RET instruction.
+
+## VDP interrupts again
+
+Right after the VDP displayed the last line of the active display area, bit 7 of VDP register S#0 is set. At the same time the interrupt signal is activated and the CPU recognises the interrupt. At this moment the IFF1 and IFF2 flags are automatically reset, preventing the CPU from handling further interrupts.
+
+However, the interrupt signal from the VDP stays active until the VDP status register S#0 is read. So if the interrupt routine executes an EI instruction to re-enable interrupts while S#0 has not been read yet, the CPU will immediately recognise the interrupt from the VDP again (it was still active after all) and proceed to execute the interrupt routine again, even though the previous call hadn’t ended yet.
+
+The result is probably clear: an infinite loop where the CPU places a new return address on the stack at every new interrupt. This will in no-time cause the entire memory to fill up with return addresses, overwriting program code and most likely causing the computer to crash.
+
+Besides the interrupt the VDP generates when the active area has been displayed, the VDP can also generate another interrupt. The moment that the VDP should do this can be set by the software in VDP register R#19. In this register a Y-coordinate can be specified. While the VDP is displaying the screen, the moment the it reaches this line an interrupt is generated.
+
+## Programming tips
+
+When writing a routine that needs to be called on an interrupt, a choice has to be made between the two available hooks. A routine attached to the H.KEYI hook can never execute an EI instruction, because the BIOS interrupt routine hasn’t read the VDP status register S#0 yet. A routine on the H.TIMI hook can enable interrupts, but has to preserve the contents of register A.
+
+The BIOS interrupt routine reads the VDP status register S#0 by directly reading the VDP’s command port, rather than first selecting the appropriate status register via register R#15 before reading the port. For this reason programs must always keep register R#15 set to 0 when the interrupts are enabled. If the program needs to read another status register, it has to disable the interrupts before doing so.
+
+It is possible to write a custom interrupt routine which replaces the existing BIOS routine entirely. If this is done, keep in mind that all registers must be preserved and don’t forget to read the VDP status register S#0. Based on this value different subroutines can be chosen within the custom interrupt routine.
+
+To end a ‘normal’ interrupt routine interrupts have to be re-enabled with an EI instruction. To prevent nesting the CPU will ignore interrupts for one more instruction after the EI instruction. This allows a subsequent RETI to return to the main program and prevents the stack from overflowing from a quick succession of interrupts, as these will only be recognised after the RET. So, the last two instructions in an interrupt routine are always:
+
+```assembly
+EI
+RETI
+```
+
+An NMI-routine should not use DI and EI instructions, because these also change the IFF2 flag. This flag needs to be preserved because IFF2 contains a copy of IFF1 while the NMI routine is executing, which needs to be restored when the NMI ends.
+
+Interrupt routines — including all routines attached to the interrupt hooks — should not take too much time. If the VDP generates a new interrupt before the routine started by the previous interrupt has ended, it will immediately be recognised when the interrupts are re-enabled. If this happens, the main program will be starved and not be able to execute another instruction.
+
+When having a custom interrupt routine in RAM, be aware when calling BIOS routines that during their execution page 0 will no longer contain the RAM with the new routine at address 0038h. In stead when an interrupt occurs the BIOS’s interrupt routine will become active. To prevent this, take care to always keep the IFF1 flag reset with a DI instruction. Also keep in mind that some BIOS routines re-enable interrupts. This is certainly done by the SUBROM, since every entry in the jump table contains an EI instruction!
+
+_[Translator’s note: For this reason, it may be preferable to use IM 2 for custom interrupt routines. Note; I would recommend to use the hooks and avoid creating a custom interrupt routine unless there are strong reasons to do so. Issues with compatibility and ever-spinning disk drives are lying in wait.]_
+
+Example program application of Interrupt Mode 2
+
+```assembly
+;
+; im2.gen - RWi
+;
+; Example of how to use Interrupt Mode 2
+;
+intVecTabAd   equ 08000h             ;Put the Interrupt Vector Table here
+intVecHalfAd  equ 080h               ;High memory address pointer
+intRoutStart  equ 08181h             ;Let interrupt routine start here
+intRoutHalfAd equ 081h               ;Address high and low
+
+im2:          di                     ;No interrupts during switch
+
+              ld hl,intVecTabAd      ;Generate IVT here
+              ld (hl),intRoutHalfAd  ;Use this as high and low address part
+              ld d,h                 ;Copy destination pointer from
+              ld e,l                 ; the source pointer
+              inc de                 ;Destination 1 byte further
+              ld bc,128*2            ;128 vectors, 1 byte extra for 256th
+              ldir                   ;Generate table
+
+              ld hl,intRoutHere      ;Routine for IM 2
+              ld de,intRoutStart     ;Put routine here
+              ld bc,intRoutLen       ;Length of the routine
+              ldir                   ;Copy the routine
+              
+              ld a,intVecHalfAd      ;Use this as high address part
+              ld i,a                 ;Set high address part
+              im 2                   ;Switch to IM 2
+
+              ei                     ;Now interrupts are permitted again
+
+loop:         jp loop                ;Endless loop
+
+intRoutHere:  equ $                  ;Code is now here
+
+              org intRoutStart
+
+intRoutIM2:   push hl                ;Save registers that are modified
+              push af
+
+              ld hl,(counterIM2)     ;Nr. of interrupts counter
+              inc hl                 ;Increase by one
+              ld (counterIM2),hl     ;And save
+
+              in a,(099h)            ;Read S#0
+              and a                  ;Does INT originate from VDP (b7=1 - True)
+              jp p,notFromVDP        ;No = Return
+
+              ld a,l                 ;Lower counter part
+              out (098h),a           ;Put it on the screen
+
+notFromVDP:   pop af                 ;Restore modified registers
+              pop hl
+              ei                     ;Interrupts are permitted again
+              reti                   ;Return to main program
+
+counterIM2:   defw 1                 ;Nr. of interrupts counter
+
+intRoutLen:   equ $-intRoutIM2       ;Length of routine code
+
+              end                    ;im2.gen
+```
+
+## Source
+
+https://map.grauw.nl/articles/interrupts.php