A Command of Your Own

Introduction

Everything you have changed so far was already in the MOS: text, a shape, a table entry. This last section adds something that was never there - a new monitor command - and in doing so uses most of what the course has shown: the free space at the end of the ROM, the table, the way handlers report back, and RST 18h messages.

Room to work

The ROM is exactly 8K, and the MOS fills almost all of it. Almost: the source ends with this:

        defb 0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh    ;1fd2  ........
        defb 0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh    ;1fda  ........
        defb 0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh    ;1fe2  ........
        defb 0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh    ;1fea  ........
        defb 0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh,0ffh    ;1ff2  ........
        defb 0ffh,0ffh,0ffh,0ffh,0ffh,0ffh              ;1ffa  ......

46 bytes of FFh - the value an erased EPROM holds - that nothing uses. (MOS 1.21 used 13 of them, S13.)

The one rule is that the ROM must stay exactly 8,192 bytes. Whatever you put in, take the same number of FFh bytes out.

Connecting a command

A monitor command needs two things: a routine, and its address in FMTBL at the entry for its letter (S8). The routine must end the way every handler does - with RET, carry clear for success or set to have the monitor print Error! (S9).

Q has no command; its entry, number 16, at 02A2h, holds ERROR. That is the slot to use.

The code

In your copy of mos12.asm, replace the first three lines of FFh bytes - 24 bytes - with this:

MYCMD:
        rst 18h                 ; print the text that follows
        defb 'Hello from your MOS',0a1h ; the last character, '!', with bit 7 set
        or a                    ; carry clear: success
        ret
        defb 0ffh               ; pad to the 24 bytes these lines replaced

RST 18h is 1 byte, the message 20, OR A and RET one each: 23. One FFh makes 24. The ! is written as 0A1h - 21h with bit 7 set - because that is how RST 18h knows where a message ends (S10).

Then change Q's table entry:

        defw MYCMD              ;02a2

Build and boot as in S5, and type Q at the prompt.

What you should see

>Q
Hello from your MOS!
>

A command that did not exist, written in the MOS's own style, connected through the MOS's own table, reporting success the MOS's own way.

Had MYCMD ended with SCF instead of OR A, the monitor would have printed its message and then Error! - the carry flag is the whole of the convention.

Where to go from here

You now know how the MOS is put together: how it starts, how it is called, how it reads keys, prints, keeps time and runs its monitor, and why each of those is built the way it is on a machine with two memories at one address. With the source and a way to rebuild it, any part of it is open to you. On a real Einstein, your MOS needs an 8K EPROM (Appendix VI); in MAME, it needs three commands.

Summary

New code goes in the 46 unused bytes at 1FD2h, keeping the ROM at exactly 8,192 bytes. A command is connected by putting its address in FMTBL at its letter's entry, and it ends with RET, carry clear for success or set for Error!.