Proposal for a new standard for API specifications

Pagina 2/5
1 | | 3 | 4 | 5

Van Prodatron

Paragon (1797)

afbeelding van Prodatron

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.

Van Prodatron

Paragon (1797)

afbeelding van Prodatron

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.

Van konamiman

Paragon (1143)

afbeelding van konamiman

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

Van Prodatron

Paragon (1797)

afbeelding van Prodatron

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?

Van Tanni

Hero (556)

afbeelding van Tanni

27-04-2007, 16:47

Well done, konamiman!

Van Morg

Master (142)

afbeelding van Morg

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

Van konamiman

Paragon (1143)

afbeelding van konamiman

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.

Van Tanni

Hero (556)

afbeelding van Tanni

09-05-2007, 13:45

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

Van konamiman

Paragon (1143)

afbeelding van konamiman

09-05-2007, 15:14

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

Van Tanni

Hero (556)

afbeelding van Tanni

09-05-2007, 15:48

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

Pagina 2/5
1 | | 3 | 4 | 5