Standard ROM entrypoints?

The place for codemasters or beginners to talk about programming any language for the Spectrum.
hjalfi
Berk
Posts: 28
Joined: Wed Jul 18, 2018 10:58 am

Standard ROM entrypoints?

Post by hjalfi » Thu Jul 19, 2018 10:05 am

So I've got this compiler: http://cowlark.com/cowgol/

It's a self-hosting fully compiled language for the Z80 and 6502, where the Cowgol compiler is written in Cowgol and you can (technically; it's far too slow to be feasible) rebuild the compiler on the target machines.

Now that I own a mostly-working Spectrum 48kB I'd like to port it to generate Spectrum executables. The compiler needs a fast random access filesystem and a proper DOS to run on a target machine, but cross-compiling for a target machine is much easier; the minimum functionality necessary is the ability to write characters to the screen. (The entire Commodore 64 runtime, for example, is 16 lines:
https://github.com/davidgiven/cowgol/bl ... untime.cow)

Does the Spectrum have reasonably portable standard system calls for doing things like printing text, etc, from machine code programs?

I've found rst $10 for printing a single character, and I've seen references to things like $0daf for clearing the screen, and I've found the huge list at http://skoolkid.github.io/rom/maps/routines.html, but that doesn't distinguish between internal BASIC routines and the nominally public ones (or tell me what the register requirements are). Does such a thing exist?
0 x

User avatar
Ast A. Moore
Dynamite Dan
Posts: 1224
Joined: Mon Nov 13, 2017 3:16 pm

Re: Standard ROM entrypoints?

Post by Ast A. Moore » Thu Jul 19, 2018 11:09 am

hjalfi wrote:
Thu Jul 19, 2018 10:05 am
I've found the huge list at http://skoolkid.github.io/rom/maps/routines.html, but that doesn't distinguish between internal BASIC routines and the nominally public ones (or tell me what the register requirements are). Does such a thing exist?
First, the document at that link is not just a “huge list,” is the disassembly of the Spectrum’s ROM in its entirety. It does tell you what the register requirements are most of the time. Second, there’s no such thing as “nominally public” routines in the Spectrum’s ROM. The BASIC interpreter and the operating system are pretty much interconnected.

I’m not entirely sure what you’re trying to achieve. There are many Spectrum-specific Z80 assemblers out there for many platforms. Unless you’re hell-bent on using the output of a general-purpose Z80 assembler and then loading it into the Spectrum manually somehow.

If you’re using an emulator, it’s normally not difficult—most will accept BIN files. Not sure how you’re planning on loading it into a real Spectrum, though. You best option is to import it into an emulator, save to a tape file from it, and then play it back into the Spectrum.

Sounds like a lot of self-inflicted pain. You’d be better off finding an assembler that can generate a TAP/TZX file for you, which you can then easily load into the Spectrum the usual way.

I apologize if I completely misunderstood your original motives, though.
0 x
Every man should plant a tree, build a house, and write a ZX Spectrum game.

Author of A Yankee in Iraq, a 50 fps shoot-’em-up—the first game to utilize the floating bus on the +2A/+3,
and zasm Z80 Assembler syntax highlighter.

hjalfi
Berk
Posts: 28
Joined: Wed Jul 18, 2018 10:58 am

Re: Standard ROM entrypoints?

Post by hjalfi » Thu Jul 19, 2018 11:29 am

I don't have an assembler. My compiler generates binaries directly. I already know how to turn these into loadable TZX images which can be used on emulators or real hardware; that's not the difficult bit.

I know that the huge list is a disassembly of the entire ROM, which is why it's not very useful to me. I don't want a warts-and-all analysis of the ROM; what I want is a curated set of useful entrypoints which can be used from machine code, which I can use to implement my language's runtime library. In particular, I need to know what BASIC's expectations are when I call these. This shouldn't be controversial --- anybody whose tried to call BASIC from machine code will need to know this stuff. I also need to know which entrypoints are stable across ROM versions so that I can produce reasonable portable binaries.
0 x

User avatar
Ast A. Moore
Dynamite Dan
Posts: 1224
Joined: Mon Nov 13, 2017 3:16 pm

Re: Standard ROM entrypoints?

Post by Ast A. Moore » Thu Jul 19, 2018 1:57 pm

Okay, let me see if I got this straight.

You’re not planning to program in assembly, only in Cowgol. Okay, that part is now clear. What I’m still fuzzy about is this: “anybody whose tried to call BASIC from machine code will need to know this stuff.” I don’t know anybody who does this (aside from the people at Hisoft). The normal course of programming is to either ignore the ROM and system variables altogether, or to use a few ROM calls for specific tasks. The latter implies the knowledge of the Spectrum ROM, as well as the differences between different ROM versions.

Machine code routines can be called from BASIC, in which case, the BC register will often be the “exchange point.” For example, if you have the following MC sitting at address 40000:

Code: Select all

	ld bc,12345
	ret
Then running PRINT USR 40000 will print 12345. The same result will be the output of the following BASIC program:

Code: Select all

10 LET a=USR 40000
20 PRINT a
You don’t really “call BASIC from machine code” per se. You make calls to the various entry points in ROM. Each will expect different parameters, depending on the routine or even an entry point. (It’s common to use entry points that are different from “normal” BASIC entry points to speed things up, for example.)

As far as portability is concerned, indeed, a few modifications to the original 48K ROM were made in 128K, +2, and +3 ROMS, and some entry points moved. Mostly, the previously empty spaces were used to hold additional routines (part of the reason a few games became incompatible with the 128K and +3 Spectrums). There were also ROMs produced for different languages (notably, Spanish, French, and I think German), which presented further compatibility issues.
0 x
Every man should plant a tree, build a house, and write a ZX Spectrum game.

Author of A Yankee in Iraq, a 50 fps shoot-’em-up—the first game to utilize the floating bus on the +2A/+3,
and zasm Z80 Assembler syntax highlighter.

User avatar
Guesser
Microbot
Posts: 121
Joined: Wed Nov 15, 2017 2:35 pm
Contact:

Re: Standard ROM entrypoints?

Post by Guesser » Thu Jul 19, 2018 2:29 pm

Ast A. Moore wrote:
Thu Jul 19, 2018 1:57 pm
What I’m still fuzzy about is this: “anybody whose tried to call BASIC from machine code will need to know this stuff.” I don’t know anybody who does this (aside from the people at Hisoft). The normal course of programming is to either ignore the ROM and system variables altogether, or to use a few ROM calls for specific tasks.
I think it's those specific tasks he's asking for a list of :P
0 x

User avatar
Ast A. Moore
Dynamite Dan
Posts: 1224
Joined: Mon Nov 13, 2017 3:16 pm

Re: Standard ROM entrypoints?

Post by Ast A. Moore » Thu Jul 19, 2018 3:28 pm

Guesser wrote:
Thu Jul 19, 2018 2:29 pm
Ast A. Moore wrote:
Thu Jul 19, 2018 1:57 pm
What I’m still fuzzy about is this: “anybody whose tried to call BASIC from machine code will need to know this stuff.” I don’t know anybody who does this (aside from the people at Hisoft). The normal course of programming is to either ignore the ROM and system variables altogether, or to use a few ROM calls for specific tasks.
I think it's those specific tasks he's asking for a list of :P
Heh. Well, he’s in for a surprise, then. I’ve seen people use the “entry point” at $33c3 for the LDIR/RET combo. Not sure what the point of it was other than obfuscation. :lol:
0 x
Every man should plant a tree, build a house, and write a ZX Spectrum game.

Author of A Yankee in Iraq, a 50 fps shoot-’em-up—the first game to utilize the floating bus on the +2A/+3,
and zasm Z80 Assembler syntax highlighter.

hjalfi
Berk
Posts: 28
Joined: Wed Jul 18, 2018 10:58 am

Re: Standard ROM entrypoints?

Post by hjalfi » Thu Jul 19, 2018 4:45 pm

Re not wanting to do this much --- so far every single Spectrum machine code tutorial I've found has used the Basic entrypoints for drawing on the screen; plus I've found two different Forth interpreters which do it, for all their I/O; plus a Pascal interpreter which does it; etc, etc... although interestingly z88dk doesn't, preferring to implement its own console driver instead.

https://chuntey.wordpress.com/tag/printing/

I can infer pretty much everything I need from the above article, but it's far too fuzzy on things like which registers I need to preserve, stack status, etc. (e.g. which routines need the system variable pointer in IY? Does anything touch the alternate register set? Flags? Interrupts?)

I was hoping for some actual hard information!
Heh. Well, he’s in for a surprise, then. I’ve seen people use the “entry point” at $33c3 for the LDIR/RET combo. Not sure what the point of it was other than obfuscation.
Probably for speed. When the Z80 executes LDIR it reads and decodes the instruction every time a byte is processed, even though it's always the same instruction. On systems where ROM is faster than RAM (the section of RAM between 0x4000 and 0x8000 is slow on the Spectrum, because it's shared with the video system, right?) then calling out to ROM for memory copies will mosty be a win.
0 x

User avatar
Ast A. Moore
Dynamite Dan
Posts: 1224
Joined: Mon Nov 13, 2017 3:16 pm

Re: Standard ROM entrypoints?

Post by Ast A. Moore » Thu Jul 19, 2018 5:28 pm

hjalfi wrote:
Thu Jul 19, 2018 4:45 pm
I can infer pretty much everything I need from the above article, but it's far too fuzzy on things like which registers I need to preserve, stack status, etc. (e.g. which routines need the system variable pointer in IY? Does anything touch the alternate register set? Flags? Interrupts?)

I was hoping for some actual hard information!
Again, there are no “universal” entry points—each programmer uses mostly arbitrary points based on his particular needs. In addition, some entry points were moved around in different Spectrum models. That’s why some BASIC compilers will work on some models but not others (hence my mention of Hisoft).

The IY register is best left alone or, at the very least, preserved, if one intends to return to BASIC from machine code. Yes, quite a few routines use the prime registers (mostly HL′, see this, for instance), so they too need to be preserved. Interrupts are enabled most of the time while the BASIC is running and flags, too, are used extensively.

The Spectrum ROM is not a collection of libraries. It’s a mishmash of a BASIC interpreter and an operating system with quite a few interdependencies. Those tutorials you refer to, simply use a subset of “most commonly used shortcuts” to ease a novice into programming in languages other than Sinclair BASIC. There’s no secret set of standard entry points circulating among the few initiated (even it there were, I couldn’t tell you—I took an oath).
0 x
Every man should plant a tree, build a house, and write a ZX Spectrum game.

Author of A Yankee in Iraq, a 50 fps shoot-’em-up—the first game to utilize the floating bus on the +2A/+3,
and zasm Z80 Assembler syntax highlighter.

Bizzley
Microbot
Posts: 124
Joined: Thu Nov 16, 2017 10:47 am

Re: Standard ROM entrypoints?

Post by Bizzley » Thu Jul 19, 2018 7:34 pm

hjalfi wrote:
Thu Jul 19, 2018 4:45 pm
I was hoping for some actual hard information!
Everything you need to know is here :

https://computerarchive.org/files/comp/ ... blyThe.pdf

Every single byte of code, every routine and subroutine, what registers are used, when they are used and how they are used. You'll see what alternate registers are used by each piece of code, what Stack operations are carried out, what the state of the interrupts are and much more. It's all in there.
0 x
"He made eloquent speeches to an audience consisting of a few depressed daffodil roots, and sometimes the cat from next door."

AndyC
Manic Miner
Posts: 251
Joined: Mon Nov 13, 2017 5:12 am

Re: Standard ROM entrypoints?

Post by AndyC » Thu Jul 19, 2018 7:48 pm

Bizzley wrote:
Thu Jul 19, 2018 7:34 pm
hjalfi wrote:
Thu Jul 19, 2018 4:45 pm
I was hoping for some actual hard information!
Everything you need to know is here :

https://computerarchive.org/files/comp/ ... blyThe.pdf

Every single byte of code, every routine and subroutine, what registers are used, when they are used and how they are used. You'll see what alternate registers are used by each piece of code, what Stack operations are carried out, what the state of the interrupts are and much more. It's all in there.
The ROM disassembly is great and certainly useful as a good guide to finding entry points which can allow you to get BASIC-like functionality. But it is is no means official nor exactly definitive - there are certainly sequences of instructions part-way through those identified which might be useful if called in the right order (for added fun: PUSH a sequence of fake return addresses to chain things in weirder ways). There is also the issue that it doesn't tell you what is "safe" across different ROM versions.

Sinclair BASIC just wasn't designed to have version independent, documented entry points in the way that, for example, the Amstrad CPC or Elan Enterprise ROMs were. It's just one great big program that you can leap into at arbitrary points to trick it into doing what you want. It may be easier to tackle the problem from the other way around, document the system calls you want to exist and ask about any that you can't find an obvious entry point for. And then test everywhere. :lol:
0 x

Post Reply