Proposal for a new standard for API specifications

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

By [D-Tail]

Ascended (8254)

[D-Tail]'s picture

09-05-2007, 23:22

Tanni, you can compare "The big picture", with "Überblick" or "Overview". It's some kind of summary, which gives you a grip on the full (=big) picture of what Konamiman is trying to state in his document in a small section of text.

By NYYRIKKI

Enlighted (5889)

NYYRIKKI's picture

11-05-2007, 20:34

Ok, it's better with flux capacitors'n stuff. Tongue

By konamiman

Paragon (1152)

konamiman's picture

13-05-2007, 11:44

Maybe I'll rename this section to "Example scenario" or the like in the next document version. But I would like to know if the document is now actually easier to understand.

By Manuel

Ascended (18233)

Manuel's picture

13-05-2007, 16:12

It helped me a lot to get the basic idea in simple language. So for me it was a good addition.

By konamiman

Paragon (1152)

konamiman's picture

09-07-2007, 12:14

Ok, just in case you're bored:

MSX-UNAPI specification 0.3 (see the changelog in the document itself)
Sample implementation in ROM
Sample implementation in mapped RAM
Sample of client software

By Tanni

Hero (556)

Tanni's picture

09-07-2007, 13:42

1.4. Glossary

API implementation name
An alphanumeric string made of up to 64 characters, which uniquely
identifies an API implementation. . . . See Section 2.5 for more details.

2.5. Rule 5: The API information routine + the implementation name and
version
. . .

The implementation name string must be zero terminated and composed
of up to 64 printable characters.

So the string has 64 printable characters and is terminated by #$00, resulting in a string of 65 characters? Zero normally isn't considered printable. Function key strings are 15 characters terminated by an additional zero, so the whole string is a power of 2.

By konamiman

Paragon (1152)

konamiman's picture

09-07-2007, 13:49

The identifier is 15 characters so that it is possible to store the string plus the zero in the 16-byte buffer ARG. There is no such limitation for the implementation name so I made it to be up to 64 chars, indeed 65 when the zero is included. Do you think that 63+zero would be more convenient?

By Tanni

Hero (556)

Tanni's picture

09-07-2007, 14:34

Yes, at least it's more ''natural'' if it would be 63+1. In Turbo Pascal, it would be convenient to declare e.g. an Array [ 0 .. 15 ] of unapi_string, where unapi_string would be String[63], i.e. 1 Byte for string length + 63 byte for the string itself. Using powers of 2 for this kind of data structures makes it easier and faster to compute the start address of a component. Even if it's unlikely to have UNAPI implementation names in arrays, it would be better to stick to such conventions, otherwise, the reader might wonder why such an ''odd'' value is used. (With a maximum of 63 characters, you also would have 2 bits left for flag usage in the length byte of the string, if necessary.)

It also would be an inconsistency to the rules for API specification identifier:

1.4. Glossary

API specification identifier
An alphanumeric, case-insensitive string made of up to 15
characters, which uniquely identifies an UNAPI compliant API
specification. For example the identifier of an API specification
for Ethernet cards could be "ETHERNET". See Section 2.1 for more
details.

2.1. Rule 1: The API identifier and version number

An API specification must have an alphanumeric identifier composed of
up to 15 characters. Allowed characters are letters (having an ASCII
code below 128), digits, and the following ones: - _ / . ( )

By the way, how is this terminated, by zero or by dollar or something else? Or do you intend to use a length byte? Most likely, you like to have it zero terminated, so the total length is a power of 2, so why violating this scheme on API implementation names without need? Most likely, the extra byte (the 64th one) will never be used in any future implementation.

By konamiman

Paragon (1152)

konamiman's picture

09-07-2007, 15:21

It also would be an inconsistency to the rules for API specification identifier:
(...)
By the way, how is this terminated, by zero or by dollar or something else?

Per section 3.2, the first step of the discovery procedure is: Copy the zero-terminated API specification identifier to address #F847 (ARG).

About how to store the identifier in the implementation itself, it is intentionally left unspecified: it does not matter, as long as the code attached to the extended BIOS hook does the comparison properly. You can see in the sample code that indeed, I store the identifiers zero terminated, but this is not manadatory.

Anyway you are right, if the identifier is 15+zero, it is more reasonable to have the name to be 63+zero.

By Tanni

Hero (556)

Tanni's picture

09-07-2007, 15:45

I just browsed the text and the code today, read it as you first came up with it a couple of month ago. It's quite difficult to keep every detail in mind. I never had the need to code things concerning your proposal, so I can only find conceptual oddities like the 64+1 name length.

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