Well done, konamiman!

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

Ok, here it is:

MSX-UNAPI specification 0.2

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

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

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

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

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.

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

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.

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

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

Quote:

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.

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?

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:

Quote:

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.

Quote:

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.