System hooks
This page was last modified 09:37, 13 August 2018 by Gdx.

System hooks

Hooks provide a way to intercept the BASIC interpreter or operating system at certain points, enabling additional, or alternative, processing to be carried out. To expand on the last sentence it is easiest to use an to be carried out. To expand on the last sentence it iseasiest to use an example. Consider for example the BIOS call CHPUT (see section 2.3). This routine is used to print text on the screen. Here is a disassembly of the first few instructions of CHPUT:

        PUSH    HL      ;STORE ALL REGISTERS USED IN HCHPU ROUTINE 
        PUSH    DE
        PUSH    BC
        PUSH    AF
        CALL    0FDA4h    ;CALL THE HOOK H.CHPU

First of all registers HL, BC, DE and AF are pushed on to the stack.Then memory address FDA4 is called.Normally,the contents of FDA4 and the following 4 bytes,is a Z80 RET instruction, immediately passing control to the instruction following the CALL.However, FDA4h is in RAM, so its contents can be altered. Let the 3 bytes, starting at FDA4h be changed, so that control is passed to another subroutine at D000h, i.e.

FDA4h:    C3 00 D0        ;JP D000h

Also let the code at D000h be as shown below:

        POP     HL      ;Get rid of the first item on the stack that
                        ;contains the return address to the hook
        POP     AF      ;Restore the registers
        POP     BC
        POP     DE
        POP     HL
        RET             ;Back to the routine that called CHPUT.

Now the item on the top of the stack is 3 more than the address from which FDA4h was called, i.e. the return address to CHPUT. Therefore, if this is removed from the stack, this will restore the stack to the state it was in immediately before calling FDA4. Also, if the next four items are popped as shown above,the stack will be as it was on entering CHPUT, so the RET instruction will exit the subroutine CHPUT. Consequently the character which was to be printed will not be! This example demonstrates how the operating system can be intercepted. The five bytes,starting at address FDA4, are know as a hook. Similar "hook" exist at many other points in the operating system and BASIC interpreter,and a list of them, in alphabetical order, is contained in the following pages.

For example, Hooks are used by MSX2/2+/Turbo R and Disk-ROM to add reserved instructions like SET INSTRUCTION or the Disk Basic instructions.

Before modifying a Hook your program will have to consider whether it is already used or not.

Address Name Description
FD9Ah H.KEYI Call: Called at the beginning of the KEYINT interrupt routine (Main-ROM at 0038h).

Usage: Used to test whether the interruption was caused by a device other than the VDP. (RS-232C, MSX-Midi, etc)
Note: The program must back to the interrupt routine if no device has caused the interrupt.

FD9Fh H.TIMI Call: Called by the KEYINT interrupt routine (Main-ROM at 0038h) just after reading the status register 0 of the VDP (Must be specified by the control register 15 on MSX2 and newer).

Usage: Synchronize the graphic display. You can add graphics during the Vblank to have a clean display.
Note: This hook is supposed to be only called when Vblank interrupt occurs (control register 15 must contain 0 on MSX2 and newer). The register A contains the value read to status register 0 when this Hook is called in order to know.

FDA4h H.CHPU Call: At the beginning of the routine CHPUT (Main-ROM at 00A2h) to display a character on the screen.

Usage: Allows the use of a device other than a screen.
Note: Register A contains the character code when this Hook is called.

FDA9h H.DSPC Call: At the beginning of internal routine DSPCSR that displays the cursor.

Usage: Allow access to other devices than the screen.

FDAEh H.ERAC Call: At the beginning of internal routine ERACSR that erases the cursor.

Usage: Allow access to other devices than the screen.

FDB3h H.DSPF Call: At the beginning of the routines DSPFNK (Main-ROM at 00CFh) that displays the contents of the function keys.

Usage: Allow access to other devices than the screen.

FDB8h H.ERAF Call: At the beginning of the routine ERAFNK (Main-ROM at 00CCh) to erase the text of fonction keys.

Usage: Allow access to other devices than the screen.

FDBDh H.TOTE Call: At the beginning of the routine TOTEXT (Main-ROM at 00D2h) to back into text mode.

Usage: Allow access to other devices than the screen.

FDC2h H.CHGE Call: At the beginning of the routine CHGET (Main-ROM at 009Fh) to read a character on the keyboard.

Usage: Allow access to other devices than the MSX keyboard.

FDC7h H.INIP Call: At the beginning of internal routine INIPAT that initializes characters font in VRAM.

Usage: Change the characters font when back to text mode (after a graphic mode).

FDCCh H.KEYC Call: At the beginning of internal routine KEYCOD of keyboard reading.

Usage: Intercept the keyboard inputs.
Note: When the Hook is called, the accumulator contains: (line number) x 8 + column number of the key pressed in the keyboard matrix.

FDD1h H.KYEA Call: At the beginning of internal routine KYEASY that decodes the keyboard.

Usage: Change the way a key is interpreted.

FDD6h H.NMI Call: At the beginning of non-maskable interrupts routine (Main-ROM at 0066h).

Usage: Designed for handling non-maskable interrupts.
Note: Unused on MSX except perhaps in the mode R800 of MSX turbo R in option.

FDDBh H.PINL Call: At the beginning of Bios routine PINLIN (Main-ROM at 00AEh) that manages the input of a program line to the keyboard.

Usage: Use the 80 columns mode, or another input device than the keyboard for example.

FDE0h H.QINL Call: At the beginning of Bios routine QINLIN (Main-ROM at 00B4h) that manages the line input with LINEINPUT instruction of Basic.

Usage: Use the 80 columns mode, or another input device than the keyboard for example.

FDE5h H.INLI Call: At the beginning of Bios routine INLIN (Main-ROM at 000B1h) that store the entered characters until STOP or RET key is pressed.

Usage: Use the 80 columns mode, or another input device than the keyboard for example.

FDEAh H.ONGO Call: At the beginning of the system routine that manages the Basic instructions like ON GOTO, ON GOSUB.

Usage: Divert access to these instructions.

FDEFh H.DSKO Call: At the beginning of Basic instruction DSKO$.

Usage: The Disk-ROM uses this Hook to write the sector of a disk.
Note: Used by the Disk-ROM.

FDF4h H.SETS Call: At the beginning of Basic instruction SET.

Usage: Divert access to the instruction or extend it.
Note: On MSX1, the instruction SET has no other effect than calling this hook and returning an error. On MSX2 or newer, the instructions SET SCREEN, SET ADJUST, SET TIME, etc call this hook to be treated.

FDF9h H.NAME Call: At the beginning of Basic instruction NAME.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FDFEh H.KILL Call: At the beginning of Basic instruction KILL.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE03h H.IPL Call: At the beginning of Basic instruction IPL.

Usage: Reserved (never used).
Note: The basic instruction IPL only calls this hook. It can be used to create its own instruction.

FE08h H.COPY Call: At the beginning of Basic instruction COPY.

Usage: Divert/Modify/Process file copie to disk
Note: Used by the Disk-ROM.

FE0Dh H.CMD Call: At the beginning of Basic instruction CMD.

Usage: Reserved (never used).
Note: The basic instruction CMD only calls this hook. It can be used to create its own instruction.

FE12h H.DSKF Call: At the beginning of Basic instruction DSKF$.

Usage: Divert/Modify/Process the instruction
Note: Used by the Disk-ROM.

FE17h H.DSKI Call: At the beginning of Basic instruction DSKI$.

Usage: Divert/Modify/Process sector reading from the records
Note: Used by the Disk-ROM.

FE1Ch H.ATTR Call: At the beginning of Basic instruction ATTR$.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE21h H.LSET Call: At the beginning of Basic instruction LSET$.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE26h H.RSET Call: At the beginning of Basic instruction RSET$.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE2Bh H.FIEL Call: At the beginning of Basic instruction FIELD.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE30h H.MKI$ Call: At the beginning of Basic instruction MKI$.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE35h H.MKS$ Call: At the beginning of Basic instruction MKS$.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE3Ah H.MKD$ Call: At the beginning of Basic instruction MKD$.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE3Fh H.CVI Call: At the beginning of Basic instruction CVI$.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE44h H.CVS Call: At the beginning of Basic instruction CVS$.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE49h H.CVD Call: At the beginning of Basic instruction CVD.

Usage: Process the instruction.
Note:Used by the Disk-ROM.

FE4Eh H.GETP Call: At the beginning of the routine GETPTR ("GET file PoinTeR"), positioning on a file.

Usage: Process the routine.
Note: Used by the Disk-ROM.

FE53h H.SETF Call: At the beginning of the routine SETFIL ("SET FILe"), position a pointer on a previously opened file.

Usage: Process the routine.

FE58h H.NOFO Call: At the beginning of the routine NOFOR ("NO FOR clause"), used by Basic instruction OPEN of Basic.

Usage: Process the instruction.
Note: Used by the Disk-ROM to process.

FE5Dh H.NULO Call: At the beginning of the routine NULOPN ("NULl file OPen"), used by Basic instructions LOAD, KILL, MERGE, etc.

Usage: Process the routine.
Note: Used by the Disk-ROM.

FE62h H.NTFL Call: At the beginning of the routine NTFL0 ("NoT FiLe number 0"), used by Basic instructions LOAD, KILL, MERGE, etc.

Usage: Process the routine.
Note: Used by the Disk-ROM.

FE67h H.MERG Call: At the beginning of the MERGE ("MERGE program files") routine, used by Basic instructions MERGE and LOAD.

Usage: Process the routine.

FE6Ch H.SAVE Call: At the beginning of the routine SAVE, used by Basic instruction SAVE.

Usage: Process the instruction.

FE71h H.BINS Call: At the beginning of the routine BINSAR ("BINary SAVe") used by the instruction SAVE of Basic.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE76h H.BINL Call: At the beginning of internal routine BINLOD ("BINary LOaD") used by the instruction LOAD of Basic.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE7Bh H.FILE Call: At the beginning of Basic instruction FILES.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE80h H.DGET Call: At the beginning of internal routine DGET, used by the basic instruction GET/PUT.

Usage: Process the instruction.
Note: Used by the Disk-ROM.

FE85h H.FILO Call: At the beginning of internal routine FILOU1 of file output.

Usage: Process the device name.
Note: Used by the Disk-ROM.

FE8Ah H.INDS Call: At the beginning of the internal routine INDSKC of disk attribute input.

Usage: Process the routine.
Note: Used by the Disk-ROM.

FE8Fh H.RSLF Call: At the beginning of the internal routine of re-selection of previous drive.

Usage: Process the routine.

FE94h H.SAVD Call: At the beginning of the internal routine of store the current drive, used by the LOF, LOC, EOF, FPOS instructions, etc.

Usage: Process the routine.

FE99h H.LOC Call: At the beginning of the internal routine LOC, used by the LOC instruction of the Basic.

Usage:
Note: Used by the Disk-ROM.

FE9Eh H.LOF Call: At the beginning of the internal routine LOF, used by the LOF instruction of the Basic.

Usage: Process the instruction.

FEA3h H.EOF Call: At the beginning of the internal routine EOF, used by the EOF instruction of the Basic.

Usage: Process the instruction.

FEA8h H.FPOS Call: At the beginning of the internal routine FPOS, used by the FPOS instruction of the Basic.

Usage: Process the instruction.

FEADh H.BAKU Call: At the beginning of the internal routine BAKUPT.

Usage: Process the instruction.

FEB2h H.PARD Call: At the beginning of the internal routine PARDEV that parses the device name.

Usage: Add a device name.

FEB7h H.NODE Call: At the beginning of the internal routine NODEVN that is called when no name has been found in the device name table.

Usage: Add a device name.

FEBCh H.POSD Call: At the beginning of the internal routine POSDSK.

Usage: Process the routine.

FEC1h H.DEVN Call: At the beginning of the internal routine DEVNAM to process the device name.

Usage: Process the routine.

FEC6h H.GEND Call: At the beginning of the internal routine GENDSP to assign the device name.

Usage: Process the routine.

FECBh H.RUNC Call: At the beginning of the routine RUNC, used by the Basic instructions NEW and RUN.

Usage: Allows the diversion of the instructions NEW and RUN.

FED0h H.CLEA Call: At the beginning of the CLEARC routine that initializes the variables table, used by the CLEAR instruction of the Basic.

Usage: Avoid erasing Basic variables, for example.

FED5h H.LOPD Call: At the beginning of the internal routine LOPDFT, initialize the variable table, used by the CLEAR instruction of the Basic.

Usage: Process the routine.

FEDAh H.STKE Call: At the beginning of the routine STKERR (stack error), used by the CLEAR instruction of the Basic.

Usage: When initializing the Basic or MSX-DOS, the MSX checks if this Hook has been modified by any cartridge using the floppy disk drive (contents of 0FEDAh different from 0C9h).

FEDFh H.ISFL Call: At the beginning of the internal routine ISFLIO that tests whether the file to write or read.

Usage: Process the routine.

FEE4h H.OUTD Call: At the beginning of the Bios routine OUTDO, output a screen character or printer.

Usage: Process the routine.

FEE9h H.CRDO Call: At the beginning of the CRDO routine that sends a CR (0Dh) and a LF (code 0Ah).

Usage: Allows you to use a printer with an automatic line feed, for example.

FEEEh H.DSKC Call: At the beginning of the internal routine DSKCHI, for the entry of the attribute of a disk.

Usage: Process the routine.

FEF3h H.DOGR Call: At the beginning of the internal routine DOGRPH, used by the instructions of the Basic of graphical tracing. (LINE, CIRCLE, ...)

Usage: Process the graphical instructions.

FEF8h H.PRGE Call: At the end of Basic program execution.

Usage: Add a routine after the execution of Basic program.

FEFDh H.ERRP Call: At the beginning of the routine ERRPRT that displays the error message under Basic.

Change or add an error message.

FF02h H.ERRF Call: At the end of the routine that displays the error message under Basic.

Add a routine after the display of message.

FF07h H.READ Call: At the beginning of the routine READY that displays the message "Ok" (or the one defined by the user on MSX2 or newer)

Usage: Add a routine after the display of prompt ("OK").

FF0Ch H.MAIN Call: At the beginning of the MAIN routine, used at each access to the Basic interpreter.

Usage: Allows you to program an interruption for example.

FF11h H.DIRD Call: At the beginning of the DIRDO routine which is called when executing instructions in direct mode.

Usage: Add a routine or prevent the executions.

FF16h H.FINI Call: At the beginning of the routine FININT that initializes the interpretation of a basic instruction.

Usage: Divert the processing of Basic instructions.

FF1Bh H.FINE Call: At the end of the routine that initializes the interpretation of a basic instruction.

Usage: Add a routine.

FF20h H.CRUN Call: At the beginning of the routine CRUNCH that transforms a Basic line into keywords.

Usage: Process the routine.

FF25h H.CRUS Call: At the beginning of the CRUSH routine that searches for a keyword in the alphabetical list in Rom.

Usage: Process the routine.

FF2Ah H.ISRE Call: At the beginning of the ISRESV routine when a keyword is found by the CRUSH routine.

Usage: Process the routine.

FF2Fh H.NTFN Call: At the beginning of the NTFN2 routine when a keyword is followed by a line number.

Usage: Process the routine.

FF34h H.NOTR Call: At the beginning of the NOTRSV routine when the sequence of characters examined by the CRUNCH routine is not a keyword.

Usage: Process the routine.

FF39h H.SNGF Call: At the beginning of basic instruction FOR.

Usage: Process the instruction.

FF3Eh H.NEWS Call: At the end of process of a Basic instruction.

Usage: Prepare the process of next instruction.

FF43h H.GONE Call: At the beginning of the GONE2 routine, used by the jump instructions (GOTO, THEN, ...)

Usage: Add a routine.

FF48h H.CNRG Call: At the beginning of the CHRGET routine, enter a character on the keyboard.

Usage: Use another Keyboard.

FF4Dh H.RETU Call: At the beginning of basic instruction RETURN.

Usage: Change the instruction process.

FF52h H.PRTF Call: At the beginning of basic instruction PRINT.

Usage: Change the instruction process.

FF57h H.COMP Call: At the beginning of internal routine COMPRT of basic instruction PRINT.

Usage: Change the instruction process.

FF5Ch H.FINP Call: At the end of the text display under Basic.

Usage: Add a routine after displaying a text.

FF61h H.TRMN Call: When an input error with basic instruction READ/INPUT.

Usage: Process the error.

FF66h H.FRME Call: At the beginning of expression evaluator routine of Basic interpreter.

Usage: Allows you to install new math routines.

Entry: HL = Text pointer.
Output: HL = Pointer to the found expression.
	VALTYP (F663h) = Type of expression value.
	DAC (F7F6h) = Value found.
FF6Bh H.NTPL Call: At the beginning of expression evaluator routine of Basic interpreter.

Usage: Allows you to install new math functions.

FF70h H.EVAL Call: At the beginning of expression evaluator routine of Basic interpreter.

Usage: Allows you to install new math functions.

FF75h H.OKNO Call: At the beginning of transcendental function routine of Basic interpreter.

Usage: Allows you to install new math functions.
Note: Removed from MSX Turbo R.

FF75h H.MDIN Call: At the beginning of interruptions routine of Midi interface input.

Usage: Process the routine.
Note: Used on MSX Turbo R with internal Midi interface.

FF7Ah H.FING Call: At the beginning of factor evaluator routine of Basic interpreter.

Usage:

FF7Fh H.ISMI Call: At the beginning of basic instruction MID$.

Usage: Runloop execute

FF84h H.WIDT Call: At the beginning of basic instruction WIDTH.

Usage: Process the instruction.

FF89h H.LIST Call: At the beginning of basic instruction LIST/LLIST.

Usage: Process the instruction.

FF8Eh H.BUFL Call: When instructions LIST detokenise a basic instruction.

Usage: Process the routine.

FF93h H.FRQINT Call: At the beginning of frequency interrupt routine

Usage: Process the routine.
Note: Removed from MSX Turbo R.

FF93h H.MDTM Call: At the beginning of the routine of Midi interface timer.

Usage: Process the routine.
Note: Only on MSX Turbo R with internal Midi interface.

FF98h H.SCNE Call: At the beginning of the routine SCNEX2 from Basic interpretor, conversion of a line number to a memory address and vice versa.

Usage: Process the routine.

FF9Dh H.FRET Call: At the beginning of the routine FRETMP from Basic interpretor, search for a free location to store the descriptor an alphanumeric variable.

Usage: Process the routine.

FFA2h H.PTRG Call: At the beginning of the routine PTRGET from Basic interpretor, to get the pointer to found a variable.

Usage: Use other types of variables.

FFA7h H.PHYD Call: At the beginning of the routine PHYDIO (Main-ROM at 0144h).

Usage: Process the routine.
Note: Used by the Disk-ROM.

FFACh H.FORM Call: At the beginning of the routine FORMAT (Main-ROM at 0147h).

Usage: Process the routine to format a disk.
Note: Used by the Disk-ROM.

FFB1h H.ERRO Call: At the beginning of the error handler routine of Basic.

Usage: Handle errors with your own routine.

FFB6h H.LPTO Call: At the beginning of the routine LPTOUT (Main-ROM at 00A5h).

Usage: Use of a non-MSX printer.

FFBBh H.LPTS Call: At the beginning of the routine LPTSTT (Main-ROM at 00A5h).

Usage: Use of a non-MSX printer.

FFC0h H.SCRE Call: At the beginning of the instruction SCREEN of Basic.

Usage: Extend the instruction for new SCREEN modes.

FFC5h H.PLAY Call: Called at the beginning of the instruction PLAY of Basic.

Usage: Extend the instruction for another sound chip.

FFCAh EXTBIO Call: Nothing.

Usage: This is not a hook. (See Extended Bios)

FFCFh H.BGFD Call: Before physical operation with disk.

Usage: Divert disk access.
Note: Removed from MSX-DOS2 v2.3x. Replaced by the routine DISINT (See Extended Bios).

FFD4h H.ENFD Call: After physical operation with disk.

Usage: Add a routine after disk access.
Note: Removed from MSX-DOS2 v2.3x. Replaced by the routine ENAINT (See Extended Bios).