HIDD Static Model

The HIDD system is broken up into a collection of classes with a strict inheritance hierarchy. A HIDD class implements a device driver for a single device or in rare cases a group of devices and provides an interface for other programs and devices to access.

In order to maintain portability of interfaces across a wide range of hardware this interface will in general not present the raw interface to the underlying hardware. Instead it will present a generic interface that describes many different hardware implementations. This allows for the best reuse of both interfaces and code.

hidd
+- disk
|  +- floppy
|  +- ide
|  +- ram
|  +- scsi
|  +- virtual
+- graphics
+- parallel
+- serial

hidd
+- disk
+- graphics
+- parallel
+- scsi
|  +- ...
+- serial

hidd
+- disk
|  +- ...
|  +- scsi
|  +- ...
+- graphics
+- parallel
+- scsi
|  +- aha
|  +- cont
|     +- isa
|     +- pci
|     +- zorroii
+- serial

The HIDD Object Model

The class model as described previously allows the definition of classes providing some degree of abstraction between types of devices (for example disk devices) and the implementation of those devices (disk controllers). It does not however address the problem of connecting the two distinct classes.

Most computer systems have some degree of flexibility about device connections -- you can add, move, or remove devices. This possibility allows for device connectivity to change (from the operating system point of view) every time the operating system starts. This coupled with the dynamic nature of plug-and-play hardware resource allocation, requires a dynamic connection model.

The HIDD system provides this by describing the connections at the object level. This has two advantages: you can easily reconfigure the connections at any time -- without having to restart the system in many cases, and it allows classes to be reused easily to support multiple instances of the same device.

The interconnection model used could be loosely described as being a bus model. All devices are connected to the object that could be considered to be their parent in the hardware of the system.

Take the example of a SCSI disk again. The SCSI disk is connected to a SCSI controller (optionally one of many). This SCSI controller is connected to some kind of bus -- for example PCI. Finally the PCI bus is connected to some central point of the system that is the parent of all available devices. This is shown more clearly in a diagram.

<!-- img src="hidd-model-obj-1.png" alt="Connection of SCSI disk" /-->

hidd
+- disk
|  +- ...
|  +- scsi
|  +- ...
+- ...
+- scsi
|  + aha
|  + cont
|    +- isa
|    +- pci
|    +- zorroii
+- ...

It is important here to realise that the connection diagram shown above does not have anything to do with class hierarchies. If we provide a slightly different version of the diagram showing class names this should become clearer.

This is arguably the most important thing to remember when discussing this topic.

Object Life-cycle

A HIDD driver can exist in different states throughout the life of the operating system. The following section describes all the states known about by the root HIDD class.

Unknown

All HIDD drivers start in the unknown state. This is the state of a driver when it has either just been loaded into memory, or when it is inside the kernel, but before it is first initialised.

At this point the driver cannot tell whether the hardware it is tied to exist, and cannot access the device. There will have been no objects created for this driver yet.

From the unloaded state, the only allowed next state is the probed state.

Probed

The probed state is entered after the driver has checked whether the device exists. Normally a driver will only be in this state when the device exists, however kernel-based drivers that cannot be unloaded will also be in this state.

Note that the driver still has not allocated any resources and there have been no instances of this driver created. It is possible for the driver to be unloaded from memory in this state, but only under low memory conditions.

Ready

The device will enter the ready state when it has been linked into the system driver list and has allocated any static resources that it requires for its own use. It is at this point that instances of the device can be created. Whilst it it is possible for the driver to be unloaded in this state, it will only happen when there are drivers in the probed or earlier states.

Opened

This can only be reached from the ready state, but signifies that there are instances of the driver created and in use by either a user program or another driver. In this state the driver will not be unloaded from memory, even under low memory conditions.

The opened state does not consider the number of instances that have been created of this driver.

Removed

When a removable device has been removed, the driver enters the remove state. Note that this does not apply to removable media such as floppy disks, but rather removable devices such as PCMCIA cards and USB devices.

This state is not normally used by many drivers, however it is available for those drivers that may require it.

Introduction

The AmigaOS is built on the Amiga's custom chips. This is a fact which is eventually discovered when you hit the rather tight limits they impose and try to circumvent them by adding new hardware. For the new hardware, you also need a device driver. But sometimes, the applications can't be made to use this new driver because the old one is compiled in or, even worse, the OS refuses to use anything besides the built in driver or, even more worse, the OS doesn't use a driver to access this chip at all.

AROS was designed to be a portable OS and be compatible to the old AmigaOS. But we had to design something which lessens these burdens without becoming incompatible or loosing too much speed. So we developed the idea of the HIDD - the Hardware Independent Device Driver.

Features

HIDDs offer a consistent API for everything one could want to do with a device. Here is a quick overview:

• Query the system for all available HIDDs or only for certain types (e.g. all serial HIDDs or all graphics HIDDs).
• Configure a HIDD
• Use a HIDD

The complete life cycle of a HIDD is like this:

1. The OS boots. HIDDs on external cards and in the ROM get installed by the OS in the global list of all available HIDDs. Also the OS searches for HIDDs installed on the hard disk.
2. The OS reads the extended romtags from all HIDDs and puts that information in the global list of all available HIDDs.
3. Some application asks for a list with the informations about all HIDDs or a specific type of HIDD.
4. The application loads the HIDD and the config plugin. This makes the HIDD initialize some internal data structures but not always the hardware because a HIDD might be the driver for several different kinds of hardware, which might or might not be available. Thus it must be configured first.
5. The application asks for the current config of the HIDD. If the config plugin has its own GUI, the application displays it. Otherwise, the application displays the information in an own window. For this, the application queries the config plugin for all available modes.
6. The application reads the config from the config plugin, then reads the list of available modes for this config (i.e. what can be changed in the current config) and displays this. Then the user can select some mode, the application changes the config and starts over.
7. When the user presses OK, the application or config plugin closes the window/GUI. The OK or Apply button must be ghosted as long as the HIDD indicates that the configuration is not OK. The application can now expunge the config plugin. If a HIDD supports saving its config, it must do so.
8. When the device is explicitly activated or used for the first time (e.g. data is written to it), it will use the configuration to initialize the hardware.
9. The user can deactivate the device and change the config if the HIDD permits that.

The HIDD Support API

ULONG HIDD_FindHIDD (struct TagItem * tags, Class ** hiddArray)

Get a list of HIDDs with the specified attributes. The HIDDs must match all attribute/value pairs in tags. Note that this is a normal function and not a method.

ULONG HIDDM_Class_Get(struct TagItem * AttrList)

Use this method on the class on a HIDD to get the static attributes (e.g. HIDDA_Type, HIDDA_SubType, etc.).

You can then use the HIDD API to query the devices for their infos. Use FreeVec() to dispose the array. HIDDV_FindHIDD_All as type gives the complete list of all known HIDDs.

The HIDD API

HIDDs are BOOPSI objects which support the Exec Device API.

LONG OM_SET (struct TagItem * AttrList)

Change some attributes of a HIDD.

The return code is 0 in case of success or != 0 in case of an error. If the return code is > 0, then it's the number of the offending tag in the list, if it's < 0, then it's an error code. You can use HIDDM_ValueToString() with the special tag HIDDA_ErrorCode to convert this error code into a string.

LONG OM_GET (Tag AttrID, IPTR * Storage)

Query a single attribute from the HIDD in general (e.g. its name and version) and the current status. You can only query attributes which are gettable.

The return code is 0 in case of success or < 0 in case of an error. You can use HIDDM_ValueToString() with the special tag HIDDA_ErrorCode to convert the error code into a string.

LONG OM_MGET (struct TagItem * AttrList)

Query one or more attributes from the HIDD in general (e.g. its name and version) and the current status. You can only query attributes which are gettable. The ti_Data fields of AttrList must be pointers of the type which is expected for the respective attribute.

The return code is 0 in case of success or != 0 in case of an error. If the return code is > 0, then it's the number of the offending tag in the list, if it's < 0, then it's an error code. You can use HIDDM_ValueToString() with the special tag HIDDA_ErrorCode to convert this error code into a string.

LONG HIDDM_BeginIO (struct IORequest *)

Initiate a device operation. See the Exec Device API for details.

LONG HIDDM_AbortIO (struct IORequest *)

Abort a running device operation. See the Exec Device API for details.

HIDDT_Config HIDDM_LoadConfigPlugin (APTR PluginData)

Tells the HIDD to load its configuration plugin. This method returns a pointer to the plugin. PluginData is a pointer with plugin-specific data. For details, look into the manual for the HIDD.

The HIDD Config Plugin API

LONG OM_SET (struct TagItem * AttrList)

Change some attributes of a HIDD Config Plugin (HIDD CP).

The return code is 0 in case of success or != 0 in case of an error. If the return code is > 0, then it's the number of the offending tag in the list, if it's < 0, then it's an error code. You can use HIDDM_ValueToString() with the special tag HIDDA_ErrorCode to convert this error code into a string.

Note that changing attributes changes only the HIDD CP, never the HIDD itself. When the HIDD CP tells you that the current config works, then you can copy the config to the HIDD.

LONG OM_GET (Tag AttrID, IPTR * Storage)

Query a single attribute from the HIDD CP. You can only query attributes which are gettable.

The return code is 0 in case of success or < 0 in case of an error. You can use HIDDM_ValueToString() with the special tag HIDDA_ErrorCode to convert the error code into a string.

LONG OM_MGET (struct TagItem * AttrList)

Query one or more attributes from the HIDD CP. You can only query attributes which are gettable. The ti_Data fields of AttrList must be pointers of the type which is expected for the respective attribute.

The return code is 0 in case of success or != 0 in case of an error. If the return code is > 0, then it's the number of the offending tag in the list, if it's < 0, then it's an error code. You can use HIDDM_ValueToString() with the special tag HIDDA_ErrorCode to convert this error code into a string.

struct TagItem * AttrList HIDDM_QueryConfig (void)

Ask the HIDD CP about its current configuration. The AttrList should be built in such a way that one can go back to the current config by loading the device for the first time and use OM_SET with this AttrList or by disabling it and use OM_SET. A typical use of this will be to save this list to a file and load it next time when one needs to configure the HIDD.

The current configuration of the HIDD CP is a copy of the HIDDs current configuration when the HIDD CP is created. Then you can change it and the HIDD CP will act as if the HIDD itself had changed. When you are done, you can apply the changes to the HIDD itself (aka OK or Apply) or just forget about them (aka Cancel).

Astuce

If you write a HIDD, then you can use the power of BOOPSI and TagItem lists to create this list. Pass this method to the superclass first and then attach your local taglist with TAG_MORE. Or you can filter the taglist of the superclass and build your own taglist (and dispose the taglist of the superclass by HIDDM_FreeConfig()).

void HIDDM_FreeConfig (struct TagItem * AttrList)

Dispose the list of attributes which you got by HIDDM_QueryConfig().

struct TagItem * HIDDM_QueryModeList (void)

Ask the HIDD CP about the currently available modes.

The taglist consists of tags which have the types BOOL, HIDDT_Limit (a minimum and maximum value), HIDDT_List (a list with string/value pairs or one-of-many selection) or HIDDT_OptionList (same as HIDDT_List but for some-of-many selection. The result is passed as a bitfield).

HIDD CPs which supply their own GUI don't need to support this tag (but most will because you need something like this internally anyway).

void HIDDM_FreeModeList (struct TagItem * AttrList)

Dispose the list of attributes which you got by HIDDM_QueryModeList().

ULONG HIDDM_Apply (void)

Apply the current config to the HIDD. If you dispose the HIDD CP, then all changes will be lost.

ULONG HIDDM_SaveConfig (STRPTR filename)

Save the current config in the specified file. If filename is NULL then save the current config as default. This might need not result in writing a file to the hard disk, if e.g. the hardware has a FlashROM or EEPROM.

ULONG HIDDM_LoadConfig (STRPTR filename)

Load the config from the specified file, or the last saved defaults if filename is NULL. As some devices will read the defaults from an EEPROM, this need not always generate disc access.

STRPTR HIDDM_ValueToString (Tag tag, IPTR value)

Convert the value value for the tag tag into a human readable string. The string returned must not be written to or be freed.

HIDD CPs which supply their own GUI don't need to support this tag (but most will, because something like this is needed internally anyway).

The application will use this value to generate the visual feedback in its GUI.

IPTR HIDDM_StringToValue (Tag tag, STRPTR string)

Convert the string string for the tag tag back into a value.

HIDD CPs which supply their own GUI don't need to support this tag (but most will, because something like this is needed internally anyway).

Also note that a HIDD can ask that you return exactly the string which was passed to you by HIDDM_ValueToString() (i.e. the string must have the same address).

STRPTR HIDDM_GetTagName (Tag tag)

Return a human readable string with the name for a tag. For example, a serial HIDD with the tag HIDDV_Serial_BPSRate might return "BPS rate". The application will use this to generate its GUI.

ULONG HIDDM_GetTagType (Tag tag)

Return the type of an attribute. Examples are HIDDV_TagType_ULONG, HIDDV_TagType_STRPTR, HIDDV_TagType_Other (i.e. something special). This can be used to generate a general GUI for a HIDD or to load and save attributes of a HIDD. Always remember that a HIDD can have many more attributes than this document describes. A HIDD can store private data in a taglist which it needs to configure itself but which should be invisible to the user.

Sample HIDDs

typedef struct
{
    struct Message ke_Message;
    ULONG          ke_Key[1];
}
HIDDT_Keyboard_Event;

dest = ((mode & 1) && src && dest)
    ```` ((mode & 2) && src && !dest)
    ```` ((mode & 4) && !src && dest)
    ```` ((mode & 8) && !src && !dest)
;

Internals

A HIDD is a normal Exec Device which creates a BOOPSI class when loaded. A HIDD is recognised by the name in the ROMtag structure. This name must begin with the four letters "HIDD" (in that order). Note that the name of the HIDD is the string after the first four letters. Also note that a HIDD need not have a unique name.

Every HIDD has an extended ROMtag structure which contains the infos needed to find a HIDD by HIDD_FindHIDD().

HIDDs are BOOPSI objects but unlike other BOOPSI objects, they are not created by classname but by the pointer returned by HIDD_FindHIDD().

Random unsorted ideas

The HIDD Tool Library (HIDDTL) must offer a way to make the process which wants to execute a method on the HIDD to wait if the HIDD is locked. It must also offer functions to lock/unlock a semaphore to allow the HIDD to block. If no locking is possible (e.g. NetBSD), then there must be a way to query this, too.

There must be a set of functions to install IRQ handlers.