Proposal for a new standard for API specifications

Paragon (1194)

26-04-2007, 11:02

Hi all MSX developers around the world.

While Dumas goes on its way, I'm somewhat bored. I started to think about random things, and one idea that came to my mind is that I did not want to maintain two separate InterNestor Lite versions, one for Obsonet and one for Dumas. One single version should fit for both, and this implies to make BIOS of both cards to be compatible.

Thinking even more, I tought that the idea could be extended to a standard generic procedure for defining APIs for new hardware. I dumped my brain to a text file and here is the result: the MSX-UNAPI specification version 0.1.

www.konamiman.com/msx/unapispc.txt

Suggestions are welcome (that's why I am posting this, actually). Needless to say, I have already (all unpublished, for testing purposes only) an Ethernet UNAPI specification designed, an ObsoNET BIOS version that follows the specification, and an UNAPI version of InterNestor Lite. B-)

BTW how can I use an arbitrary text for hyperlinks (other than the linked address itself) in forum messages? The URL tag doesn't seem to allow me this.

Aangemeld of registreer om reacties te plaatsen

Van cax

Prophet (3740)

26-04-2007, 11:22

{url=http://your.host.address/and/file/name}text to show{/url}

Just replace { with [ in the example above.

Van konamiman

Paragon (1194)

26-04-2007, 18:41

Thanx, cax. To be applied from the next hyperlinked message.

Van Morg

Master (142)

26-04-2007, 19:21

Konamiman, a msx master, society leader like you, should know how to hyperlink a web address. May be you are too busy developing Dumas to remember it :-D

Van [D-Tail]

Ascended (8263)

26-04-2007, 19:53

Well, although I know sh*.*t about developing in ASM and things, I do know a bit about APIs . And if you'd want my useless opinion, I think it's a pretty cool idea. That is, if developers are going to work more in teams, rather than solo'ing a code job. Otherwise, APIs are pretty much pointless. On the other hand, regarding new hardware, APIs are a great way for the novice to easily understand and start coding right away.
By the way, great document, Nestor! University style ^_^

[Obsolete note]Of course I didn't read the full specification document.[/]
[Less obsolete]MSD, maybe your GFX9K lib and thread lib (interesting!) could be adapted to this system? Prodatron, would SymbOS development take profit of such a system?[/]

D-'I really don't know sh*.*t'-Tail

Van NYYRIKKI

Enlighted (6033)

27-04-2007, 01:46

Ah, what a perfect solution to problem we don't have!

I can now understand better how you can make so bug free code, but if I need to start reading this kind of standards MSX does not feel hobby anymore. How ever theoretically I like this kind of fool proof documentations.

Just remember: If you do right things totally wrong you might end up with usefull solution, but if you do wrong things totally right it is just pure waste of time.

Van konamiman

Paragon (1194)

27-04-2007, 10:41

Ah, what a perfect solution to problem we don't have!
Well, I actually had this "problem" when thinking about Obsonet-Dumas compatibility. I simply tought that extending the solution I designed (to make both APIs compatible) to a standard could be an useful idea to someone, somewhere, some day.

but if I need to start reading this kind of standards MSX does not feel hobby anymore
Well, I'm sure you did read MSX2 Technical Handbook, right?

Just remember: If you do right things totally wrong you might end up with usefull solution, but if you do wrong things totally right it is just pure waste of time.
Nice sentence, even though I didn't completely understood it.

Van NYYRIKKI

Enlighted (6033)

27-04-2007, 11:31

Well, I'm sure you did read MSX2 Technical Handbook, right?

MSX is a hobby as long as you enjoy using it and developing soft/hard for it. I don't see why standarizing things "unhobbytizes" MSX. But hey! I'm not going to shoot at your head if you prefer to completely ignore this proposal. It is just a proposal after all.
Sure I did read the MSX2 technical handbook (BTW you have done a great job with it!) but it was not even near as hard to read as your standard definition.

I've not anything against standards, they are great to be available, but there are different possibilitys to do things.

I can for example say "Readers of this forum message (later referred as readers) may or may not agree my point of view completely or partially and no claim to the contrary is expressed or impressed." or I can say "Feel free to disagree."

I happen to like the second version better.

Van konamiman

Paragon (1194)

27-04-2007, 12:19

Sure I did read the MSX2 technical handbook (BTW you have done a great job with it!) but it was not even near as hard to read as your standard definition.
Then the problem is HOW have I written the document? Ok, I agree, it is not easy to read after all. I could write an additional document, or a new section inside the document, providing the big picture.

Anyway here is an ultra-compact summary. When you want to define a new API:

1) You choose a short name for it (e.g. "ETHERNET" ).
2) You design a set of routines for it. Two basic conditions: a) Execution from page 1 or page 3. b) One single entry point, to be called with the routine index specified in A.

And when you implement any such API:

1) You choose a name for it (e. g. "My wonderful Ethernet API implementation" ) and a version number.
2) You implement the specification routines (including the mandatory information routine, which tells the implementation name and version), and optionally, additional implementation-specific routines.
3) You patch extended BIOS so that your implementation can be discovered by calling the EXTBIO hook with DE=#2222 and the specification name copied to ARG.

The beautiful thing here is that multiple implementations of the same API, or different APIs, may be installed simultaneously, and all of them can be sepparately discovered and used.

BTW I had already planned to include code samples in further versions of the document, I hope it will make things clear.

Van Prodatron

Paragon (1843)

27-04-2007, 13:40

Prodatron, would SymbOS development take profit of such a system?

No, unfortunately not. First this specification is designed for using APIs in the MSX-DOS environment, and those drivers won't work in the SymbOS envirnment. Second in SymbOS you are usually using messages for communicating with other components: Instead of using registers and CALLs, you prepare a message and send it to another task.

Van konamiman

Paragon (1194)

27-04-2007, 13:43

Surely, for SymbOS a similar standard could be defined. But that's not my work I guess.