MSX UNAPI specification

Two days without touching a computer and you have almost redesigned the UNAPI specification! Let's try to clarify things a little.

Ok, but please don't take the the suggestions as negative critics. I'm only trying to improve what already looks like a good spec to me. It would probably be easier for me just to build it following my own standards, but I really liked the UNIAPI philosophy above all. This is why I'm hoping to made viable for the Universal OPL driver to have an UNAPI interface.

List all the UNAPI extensions connected to a MSX. Kind of a "dir" of the extensions.
This is not possible since implementations will only react when its own spec identifier is queried and will remain completely silent and undetected otherwise. At most, you could develop an utility that takes a list of known spec identifiers (for example from a configuration file) and lists all the implementations for all the identifiers in sequence.

Yep, I noticed that limitation. This is why I required the spec to try to include such a feature. It shouldn't be hard to implement on the driver side (just a broadcast function for each driver to spit it's signatures). But OTOH, implementing it on the client side requires manual effort either from the user or from a centralized signature maintainer.

Request an extension to unload itself. ROM extensions would just remove themselves from the chain. This can be used to easily solve eventual conflicts.
Installed UNAPI implementations do not act as a "chain", except in the discovery procedure. You either invoke the routines of one implementation or of another, so I don't understand what kind of "conflicts" could arise (could you explain which conflicts you envision?)

The "chain" I mentioned is the EXTBIO chain formed by a sequence of installed extensions. On install each extension copies the old EXTBIO to an internal place and places their own EXTBIO call. This forms a chain of extensions, but the only way to release a node is requesting the extension itself (because there's no standard for the place where the previous EXTBIO was copied) to release it.

Upon release request, extensions should release the RAM they allocated and get themselves out of EXTBIO chain too. Currently, there's no way to do it on the UNAPI standard.

The situations I see for the release (or unload) feature are:

1) Many MSX are very limited on RAM (think of 128KB or 256KB models).
1.1) The user may have loaded some extensions, then don't have enough RAM to load a new one he desires.
1.2) The user would then list all extension installed (with the resources used), and choose one of them to be uninstalled. He uninstall the extension and now have enough free memory for loading the new one

2) Conflicts: Since we're dealing with software, unexpected bugs and collateral effects can arise when multiple distinct softwares are loaded on an unprotected system like the MSX-DOS2. There's no way to know previously what kind of conflicts will happen, but by experience we just know they'll happen. It can be some subslot operation an extension does before a second extension runs, and so on. Remember when the Turbo-R came into market and it's new type of Kanji driver conflicted with MEMMAN? That's the kind of situation I'm talking about.

Currently the only way to deal with both situations mentioned above is to reset the MSX and do not load some extensions. Not very aligned with the MSX-DOS2 philosophy: Usually DOS2 don't require a reset to free resources or for reconfiguration.

I would like that at least the page-2 could be used to, for a good reason (IMO): I'm interested on making a single ROM containing both the MSX-Audio BIOS and the Universal OPL driver. But that would require the Universal OPL driver to reside on the page-2, because the MSX-Audio BIOS already takes the entire page-1 for itself and leaves little room for relocation.
I can think of a few options for this:

• Use one single entry point in page 1 for both Audio and OPL driver code. When having to invoke a page 2 routine, simply use a CALSLT from your page 1 routine.

  Unfortunately, that's not a viable option, because of the high CPU usage. All that slotswitching would require more CPU time than the translation algorithm itself.

• Place the entry point for page 2 routines somewhere in page 3, and do a CALSLT to your slot's page 2 routines from here.

  Not a viable option too. Because one of the main possibilities of the driver is to (1) TurboFix old games and (2) Allow OPL1/2/3/4 support on them (stereo included).

  Those old games requires the BDOS to be placed as high as possible. This is why many of my HDD versions require DOS2.41 or even the RUNDOS tool. Loading RAM routines on page-3 would lower the RAM top even more, making it impossible for such old games to run.

• Use a mapped ROM and put each piece of code on a different ROM page (you need to place the entry point the main page and do an inter-page call in this case).

  This would be only viable for new hardware. But one of the ideas is to make a ROM version of the Universal OPL driver for both the Philips and Toshiba Music Modules. Those don't have rom mapping, but do support 64KB of linear ROM.

• Violate the standard and put your entry point in page 2 anyway. I promise I won't sue you. As long as your client application developers are aware (which implies that you must clearly document this spec violation), it should all work fine.

Yep, that's the path I'm following. But unfortunately making an incompatible extension would throw away all the advantages of the standard, nearly nullifying the time invested to port it to the API. My idea is to try to negotiate with you an upgrade for the UNAPI to v1.1 if possible. This v1.1 would allow page-2 and other modifications I'll detail below, that are needed for the OPL driver to run efficiently.

Note anyway that if you have two entry points, you effectively have two specs and two implementations that are in principle independent of each other. If one depends on another, again you should clearly document that.

Well, to be sincere it currently already has three implementations, and a fourth one may come into light too.
It will be documented, since the last two implementations are highlevel and depend on the 1st one, the lowlevel.

That's sure a heavy burden on the poor Z80A for each OPLL write.
The RAM helper, as its name says, is intended to be a help for implementation and client developer applications, but it is not mandatory to use it. You can perfeclty use the same code of your current routine, except that instead of "call WRTOPLL", you would use something like "ld a,WRTOPLL : call ENTRYPOINT". You should document this in your specification documentation so that client application developers are aware.

And of course, there is for sure room for improvement in the RAM helper itself; I am not a perfect programmer. Any suggestion for optimization will be welcome.

Ok, but please don't take the the suggestions as negative critics.
I have never done such thing. Improvement suggestions are always welcome.

Yep, I noticed that limitation. This is why I required the spec to try to include such a feature. It shouldn't be hard to implement on the driver side (just a broadcast function for each driver to spit it's signatures).
Yes, some kind of broadcast call would do the trick. But anyway, I don't think this feature is essential. After all, implementations are installed by the user, and the user should be aware of what he has installed. I don't think anyone will install 20 UNAPI related programs or so. :-)

Upon release request, extensions should release the RAM they allocated and get themselves out of EXTBIO chain too. Currently, there's no way to do it on the UNAPI standard.
This is not a new problem on the MSX system. If you install a TSR program A, which patches a hook, and then install another TSR program B which patches the same hook, you can't uninstall A if you don't uninstall B first. And this happens regardless of being UNAPIfied or not.

Currently the only way to deal with both situations mentioned above is to reset the MSX and do not load some extensions. Not very aligned with the MSX-DOS2 philosophy: Usually DOS2 don't require a reset to free resources or for reconfiguration.
I understand your point: a design that does not force to reset is cleaner. But we are speaking about MSX here. This is not a workstation with some dozens of programs open, nor a server that must be up and running 24/7. If you need to reset, go and reset, the reboot takes just a few seconds. That's the big advantage of an obsolete system.

Loading RAM routines on page-3 would lower the RAM top even more, making it impossible for such old games to run.
You just need four bytes for a CALSLT to your entry point. Maybe you can even use the area for your slot at SLTWRK for this.

Yep, that's the path I'm following. But unfortunately making an incompatible extension would throw away all the advantages of the standard, nearly nullifying the time invested to port it to the API.
I don't think it is a so big problem. The reason of existence of an UNAPI implementation is to provide services to client applications. If the client applications developers are aware of any possible deviation from the standard, there should be no problems.

My idea is to try to negotiate with you an upgrade for the UNAPI to v1.1 if possible. This v1.1 would allow page-2 and other modifications I'll detail below, that are needed for the OPL driver to run efficiently.
Negotiate? Hummm, how much will you pay to me? Just kidding, of course I appreciate your suggestions and I will use them to revisit the UNAPI standard.

Ok, but imagine the case of a user with 1MB of RAM on its MSX and a CF card. With that much RAM and a fast disk, it would be more comfortable just to load all needed extensions and even MEMMAN. But that would require AUTOEXEC.BAT, AUTOEX2.BAT, AUTOEX3.BAT and REBOOT.BAT. Quite a nightmare to manage.
That's true. DOS is really lacking a standard mechanism to allocate memory on page 3. That's why I included the slot+segment hooking capability on the RAM helper, to at least minimize the problem.

But again the incompatibility with default tools problem arise and the main benefits of porting the OPL driver to UNAPI are nullified.
The only "default tool" currently is APILIST. Anything else are client applications, which are aware of the standard violation.

By the way, I just took a look at APILIST and I see that it only uses RDSLT and CALSLT to access implementations. Therefore it will work fine with page 2 entry points.

Anyway I can understand that you want to invoke page 2 code when you are in ROM, but it makes no sense when you load your code in RAM. You can simply allocate two segments and invoke both via page 1. DOS 2 even provides an inter-segment call routine that makes this task trivial.
Same deal here, the problem is performance. Can you imagine doing all this extra slot/mapperswitching on each OPL register write? We'll need an aditional Z80A just for that!
I understand that you don't want to deal with slot switching for performance reasons. But don't worry about segment switching. It is just an OUT instruction (plus a couple of LDs on DOS 2), it should be fast enough.

I needed to know if you were open to discuss improvements to the UNAPI to upgrade the specs to v1.1.
Of course I am.

I'll post my proposition on a post below
These seem quite reasonable. Don't wait for me, go ahead and implement them in your software. I will study them for a future version of the UNAPI spec as soon as I have some time.