Proposal for a new standard for API specifications

Page 2/5
1 | | 3 | 4 | 5

By Prodatron

Paragon (1801)

Prodatron's picture

27-04-2007, 13:51

Suggestions are welcome (that's why I am posting this, actually).

Hi Nestor,

yesterday I had the time to read most of the specification. I am not very experienced in using hardware drivers in MSX-DOS, so I can't make much comments here, but it was quite interesting for me.

There is just one point I would like to make a comment:

2.4. Rule 4: Routine number ranges
[...]
Numbers must be assigned to routines in increasing order, starting
with 1 for specification routines and starting with 128 for
implementation-specific routines; it is not allowed to leave holes in
the function number ranges.

I guess you add this rule, because it would make an easy and fast jump-table possible.
Sometimes I like to group functions of the same family in a special number range:

16 = function 1 of type A
17 = function 2 of type A
18 = function 3 of type A

32 = function 1 of type B
33 = function 2 of type B
34 = function 3 of type B

This makes it possible to add a type A function later in the same number range, if you leave enough space between the ranges.
But I guess it is more important to have fast and short code, so indeed I would keep your rule.

By Prodatron

Paragon (1801)

Prodatron's picture

27-04-2007, 13:56

Surely, for SymbOS a similar standard could be defined.

Very true indeed... I think some of the existing SymbOS message definitions are a little bit "dirty" (as an example, words inside a message packet should only be placed at even positions - but sometimes it's not like this). It's too late to change this for the existing ones, but a general spec like yours (maybe not sooo big Wink ) for the future may help.

By konamiman

Paragon (1157)

konamiman's picture

27-04-2007, 14:55

This makes it possible to add a type A function later in the same number range, if you leave enough space between the ranges.
Function numbers are completely arbitrary, you define them as constants in code and then you forget about them. You can always group the function descriptions per type instead of number in the documentation, even if this causes numbers not to be consecutive.

but a general spec like yours (maybe not sooo big ) for the future may help.
It is not so big when you get the main ideas, it is only very very detailed. That's my style. Smile

By Prodatron

Paragon (1801)

Prodatron's picture

27-04-2007, 15:07

Function numbers are completely arbitrary, you define them as constants in code and then you forget about them.

Yes, that's true. Btw, will you be on the RetroEuskal this year?

By Tanni

Hero (556)

Tanni's picture

27-04-2007, 16:47

Well done, konamiman!

By Morg

Master (142)

Morg's picture

27-04-2007, 17:43

As leader of the msx society, Konamiman is training hard his brain to guide us through the toughs paths of the BIOS

By konamiman

Paragon (1157)

konamiman's picture

09-05-2007, 11:51

Ok, here it is:

MSX-UNAPI specification 0.2

Check out section 1.5, "The big picture". Hope it helps to make things clear.

By Tanni

Hero (556)

Tanni's picture

09-05-2007, 13:45

Can you give us a short summary on what you have changed in version 0.2?

By konamiman

Paragon (1157)

konamiman's picture

09-05-2007, 15:14

The document contains a version history at the end. I just added section 1.5, "The big picture".

By Tanni

Hero (556)

Tanni's picture

09-05-2007, 15:48

Nice story indeed, but I don't understand why it is called ''The big picture''.

Page 2/5
1 | | 3 | 4 | 5