
Command Sets for Devices
========================

There has always been the problem that people made incompatible
extensions to the device command set. Doing a low level format on a
TD_GETGEOMETRY trackdisk command is probably the worst example for
this that anyone can think of.

Amiga International intends to solve this problem now by specifing
new rules that EVERY device has to adhere if it wants to be
compatible to any OS release beyond OS 3.1 (V40).

WARNING!
========

If you don't follow these rules when writing or updating a device
driver, we will have to list your device publically as violating the
Amiga International programming standards! And it will make the
system crash which most likely isn't satisfactory to your customers!


Rules for Device development
============================

Rule #1: Support IOERR_NOCMD
----------------------------

In 1991, Commodore specified publically and in writing that any
Exec style device must return IOERR_NOCMD on any unknown command
value [RKM Libraries, 3rd Edition, page 924]. Note that this
specification was for compatibility to OS 2.0 and that five years
have gone by in the meantime. There was enough time to adapt.

    Returning IOERR_NOCMD on any unknown command value is a *MUST*!
    If you don't do this, you break things!

Remember, this is an old rule. We can no longer tolerate violations
of this rule!


Rule #2: Don't modify Reserved Command Semantics
------------------------------------------------

Up to and including OS 3.1 (V40), custom device commands usually
started at CMD_NONSTD. Each developer added commands for custom
device features at will. This lead to messy and incompatible
devices and strange compatibility tricks to identify device
capabilities.

As of January 1st, 1996, Amiga International reserves two ranges in
the set of command values for future enhancements. Only commands as
specified by Amiga International may be used here. It is illegal for
a device developer to randomly "add" custom commands or
command features within these reserved areas!

There are 65536 command values posisble with io_Command:

    $0000 - $3fff       old style and 3rd party commands
    $4000 - $7fff       RESERVED AREA!
    $8000 - $bfff       old style and 3rd party commands
    $c000 - $ffff       RESERVED AREA!

To say it again: Commands in the reserved areas may only be
assigned and specified by Amiga International. Any "custom"
implementation of these commands or other commands in these
reserved areas is illegal and violates programming standards!

As of this writing, not that many new style commands have been
defined. The interface to new style commands is described in a
separate document "NewStyleCommands".


Rule #3: Check for new style commands before using them
-------------------------------------------------------

Have you read "NewStyleCommands" yet? Yes? Then you know that you
may only use new style commands after checking the device type and
capabilities via the new style NSCMD_DEVICEQUERY.

Heinz Wrobel
<heinz@amiga.de>
