Atom utility ROM writing guide?

[roganjosh]

Is there a guide anywhere that documents how an Atom utility ROM (A000) can/should be programmed? I'm meaning the sort of guides that were available for programmers of BBC ROMs - those that described any required header format, bytes & vectors, languages/service ROMs, entry points,
banners, copyright messages etc and how they should be set up. Not that the ATOM has any/some/all of such functionality - it's just a convenient way of describing the level of documentation I'm after. I'd like to be able to fill a ROM with some of my own machine code and then access it using whatever the preferred ATOM method(s) is/are.

The only things I can see from internet searches are that (e.g.) utility ROMs can have #AA & #55 marker bytes to identify themselves, they can contain vectors pointing to OS interpreter addresses and a block of command jump tables - but, as this info was gleaned from existing ROM disassemblies, there was no detail/description of any of this.

Alan

[roland]

There is no such guide. The Atom does not have any standard structure like the Beeb and Electron. There are no language ROMs or service ROMs.

There are three common ways of initiating a ROM:
1. By generating an IRQ on reset, like the Econet and AtoMMC do
2. By linking to an address, the Program Power Toolbox uses this
3. Most common for Basic expansion, a check byte of #40 at #A000 and #BF at #A001 followed by a (jump to) a statement interpreter.

I am happy to explain more of the third method later this week when I am at a better keyboard then my iPad.

PS: if you want to start immediately you can use http://acornatom.nl/hardware/atinpc/html/pcutil.htm for inspiration.

[roganjosh]

Thanks Roland.

I'd certainly appreciate a good explanation of the BASIC extension method. I can see it being useful for code invocation. Even though my code currently goes nowhere near BASIC, the extension method might provide an easy interface to it for the user (no need to remember link addresses etc).

Alan

[oss003]

There is another method to add extra commands.
PCharme has an option to add extra commands in a table and link the commands to asm code.
It is in the PCharme manual on page 9:
https://drive.google.com/drive/mobile/f ... sp=sharing

Greetings
Kees

[roganjosh]

It seems there are more methods than you can shake a stick at.

Thanks for that.

Alan

[roland]

The Atom Basic interpreter starts searching for a statement in the Basic ROM at #Cxxx and MOS ROM at #Fxxx. If the statement is not found then the Basic looks if there's a Floating Point extension installed at #Dxxx. If so, it hands over the control to the search routine in the Floating Point ROM. If the statement isn't even found in the Floating Point ROM then it looks if there's a utility ROM at #Axxx to search for the statement.

So in an Atom you can have one expansion ROM in socket 24, e.g. WORD or CALC. But BITD this wasn't enough and within the Dutch Atom User Group more than one expansion board for more utility ROMs were created. We called them switchboards (schakelkaart). The idea is the same as the sideway ROMs in a BBC Micro. This way we could install two, four or even 8 different utility ROMs in the Atom. Selecting a ROM was just a matter of writing the ROM number to #BFFF. But when these boards became widely in use some problems arose:

• The switching had to be done manually but not all Atoms had the same ROMs at the same positions.
• Some ROMs change the system vectors to their own routines (e.g. 1200 baud loading and saving or text in a CLEAR 4 mode). When another ROM is selected then the vector points to an invalid address which made the Atom crash or hang.

So that's when the SOS (Switch Operating Systems) came in. The Beeb has this build in the MOS ROM, it will take care of automatic switching between sideway ROMs and handle vectors pointing to a certain ROM. The most user friendly and most used SOS for the Atom is Branquar. It works with most boards and even these days it's supplied with the AtoMMC ROMs at #Exxx. But there was one slight problem: the Floating Point ROM must not jump to #Axxx but to this SOS. So the FPROM was changed to make a three-way decision of what to do when a statement is unknown:

• It looks for an SOS at some space in memory (at first #Exxx was popular because drives were not that common), later was #1xxx widely used and nowadays the AtoMMC ROM has it located it back in the #Exxx area, somewhere around #EB80 or so). If a SOS is found it jumps to the SOS.
• If no SOS is found then it behaves like the old way: look for a utility ROM at #Axxx.
• If even no utility ROM is found then there always ERROR 94 as a last resort.

So, if the Atom has a SOS installed and one or more utility ROMs are available then the active ROM is the first one to search for the statement. If it doesn't recognize the statement the SOS will catch ERROR 94 as it is thrown by the utility ROM. The SOS will save the current vectors and increase the ROM number, activate the new ROM and offer the unrecognized statement to the next ROM. If no ROM knows about the the statement the SOS will notice that all ROMs have been searched but on one can execute it, so the SOS generates the ERROR 94 to stop searching and notify the user or programner that there's a mistake.

So to write a utility ROM with additional statements you need to:

• Identify that it's a utility ROM by starting with #40 #BF (actually the only test if for #BF at #A001)
• Start an interpreter routine or have a jump to a routine at #A002. The SOS jumps to this address.
• Have a table with statements, it ends with #C558
• The statements and other code or data

In assembler (this example is written in SALFAA, also an expansion ROM at #Axxx):

The identification:

Code: Select all

  340 :PCROM     .BY #40,#BF

The interpreter which searches the table for the statement:

Code: Select all

  360\interpreteerroutine
  370 LDX @#FF
  380 :SEARCH0     LDY #5E
  390 DEY
  400 :SEARCH1     INX
  410 INY
  420 :SEARCH2     LDA TABLE,X
  430 BMI SEARCH4
  440 CMP (#05),Y
  450 BEQ SEARCH1
  460 DEX
  470 :SEARCH3     INX
  480 LDA TABLE,X
  490 BPL SEARCH3
  500 INX
  510 LDA (#05),Y
  520 CMP @#2E			\ this is the dot for abbreviation of the statement
  530 BNE SEARCH0
  540 INY
  550 DEX
  560 BCS SEARCH2
  570 :SEARCH4     STA #53
  580 LDA TABLE+1,X
  590 STA #52
  600 STY #03
  610 LDX #04
  620 JMP (#52)

The statement table:

Code: Select all

  640 :TABLE
  650 .AS "CHAIN"           ; .DB KETTING
  660 .AS "FILECNV"         ; .DB FILECNV
  670 .AS "GWINDOW"         ; .DB GWINDOW
  680 .AS "GWOFF"           ; .DB GWOFF
	....
  910 .AS "XTRIANGLE"       ; .DB XTRIANGLE
  920 .DB #C558

You can of course convert this source code to native Atom assembly, BeebASM, CA65 or whatever your favorite assembler is.

This is quite a simple approach to write expansion ROMs for the Atom that is compatible with most expansion ROMs. I remember that the Screenrom was not working in this setup, it changes the vectors too often or so. There are no fixed signatures for a ROM name, type of ROM (service or language), copyright strings and version numbers but you can of course add it to your own ROM.


Kees mentioned the P-Charme ROM. This is a very, very clever ROM which also provides a lot of extra statements and program structures like XIF-ELSEIF-ELSE en WHILE-END. But it has also a feature to add several additional statements outside of the Axxx block. It uses its own tables in the Atom memory. There may be more than one table with additional statements.

[roganjosh]

Great heavens Roland, that's a mammoth piece of work! Much appreciated.

Alan

[oss003]

Hi Alan,

I once wrote a Demorom with commands to show how you can add a normal interpreter, a *-command interpreter and some commands to show how to read a variable, number or string. The assembly list and the source code is attached. I used CC65 to assemble the code.

https://www.stardot.org.uk/forums/viewt ... rom#p87138

You can test it by unpacking ROM.zip into Atomulator MMC directory.
Then start Atomulator and type:

*LOAD DEMOROM 7000
?#BFFE=1
DEMONR 5
DEMOVAR A
DEMOTXT "TEST"
DEMODOS
*DEMONR 5
*DEMOVAR A
*DEMOTXT "TEST"

Greetings
Kees

[roganjosh]

Hi Kees,

Thanks once again. All this will keep me going for a while. I've used DASM for many years but may also look at cc65 as I see that, from your code, it uses '$' and '#' in the same way. Learning the intricacies of a new machine is far less confusing and less error-prone when you're not fighting against alternative symbol meanings at the same time. I'll hurriedly say that both styles undoubtedly have their good points for fear of starting a compiler war.

Alan