HDDRIVER Modules
----------------

Since version 11 HDDRIVER supports launching executables, called HDDRIVER
modules, early during the boot sequence, even before the actual driver
HDDRIVER.SYS. The main difference between modules and AUTO folder programs
is that a module is launched *before* HDDRIVER.SYS, whereas an AUTO folder
program is launched *after* HDDRIVER.SYS. A typical module provides
functionality HDDRIVER can make use of during the boot process, like a SCSI
Driver providing access to non-standard interfaces, e.g. USB. Modules can
also provide other functionality.
For some programs it can be useful if they can be launched both as a
module and from the AUTO folder.


Module Execution
----------------

Like HDDRIVER.SYS modules are located in the root directory of the boot
partition. This does not necessarily have to be drive C: because you can
also install HDDRIVER on other drives. Modules run in the same type of RAM
(ST-RAM or TT-RAM) as HDDRIVER.SYS, depending on the HDDRIVER installation
settings configured in HDDRUTIL.
Module filenames have the format "HDDRMODn.SYS", with n being a digit from
0-9. n determines the module execution order. During the boot process (if
HDDRIVER was configured accordingly with HDDRUTIL) modules are executed
until no further module file for an increasing n is found. HDDRIVER.SYS is
launched after the last module.
If there are any issues with loading a module, e.g. errors when accessing
the boot partition where the module files reside, the next module is
launched, and finally HDDRIVER.SYS.
Note that modules cannot dynamically allocate additional memory. This is
due to technical reasons imposed by the TOS boot process.
Modules are always run in supervisor mode. MODSTART.S and SAMPLE.C should
be studied in order to learn more about HDDRIVER modules.


Modules implemented in C
------------------------

Depending on its functionality it may be useful to launch the same binary
either from the AUTO folder or as a module. MODSTART.S is a piece of Pure C
initialization code that enables a program to be executed by TOS and also as
a module. Please see the comments in the source code for details. In
particular MODSTART tweaks the memory management of a program, so that it
can properly be executed during the boot process.
It is sufficient to just add MODSTART as the first item to be linked (e.g.
before PCSTART) to the Pure C project file. The MODSTART startup code
automatically detects whether a binary was launched by TOS or as a module.
Modules using MODSTART must terminate with Pterm0(), Pterm() or Ptermres(),
so that MODSTART can override these methods.
Their main() method must not be terminated just by a C return statement.
Modules cannot return any result.
In case a program needs to know at runtime whether it was launched as a
module, the function isHddriverModule() declared in HDDRMOD.H provides this
information.


Modules implemented in assembler or not using MODSTART
------------------------------------------------------

Modules implemented in assembler are launched by calling their start
address + 4. In case they do not use MODSTART they have to free any
unused memory and must terminate with RTS. They must not execute any
Pterm*() call. See the comments in MODSTART.S for details.
The simplest possible module in assembler (effectively doing nothing) is:

	nop             ;the module entry point is the start address + 4
	nop
	pea (a2)        ;A2 points to the module start address
	move #73,-(sp)  ;MFREE
	trap #1
	addq.l #6,sp
	rts


Sample Module
-------------

The C sample module in the SAMPLE folder is a simple module that is aware
of whether it was started as a regular program or as a module.


Afterburner040 PMMU Fix Module
------------------------------

The Afterburner040 hardware for the Falcon requires the 68040 PMMU to be
initialized in a certain way in order to avoid caching issues with DMA
transfers. Until HDDRIVER 11 the HDDRIVER binary dealt with this
initialization. Since HDDRIVER 12 the initialization code is provided by
a module and a program for the AUTO folder, resp. The sources for this
module are located in the AB040MMU folder.
The new approach relieves HDDRIVER of platform-specific code and is more
flexible than having hardcoded AB040-specific code in the HDDRIVER binary.


SCSI Driver Modules
-------------------

SCSI Drivers, e.g. for USB hardware, are typical examples of HDDRIVER
modules. During the boot sequence HDDRIVER.SYS scans all available buses,
so that any mass storage device supported by a SCSI Driver can be managed
by HDDRIVER, as if support for this device was built-in. HDDRIVER features
like XHDI support or booting the AUTO folder and accessories from any
partition are automatically available for any drive managed by HDDRIVER.
Because of this, SCSI Drivers launched as modules should *not* install BIOS
or XHDI code of their own.
HDDRIVER maps any XHDI major device ID to its corresponding SCSI Driver bus
ID by dividing the major device ID by 8. This provides for 8 XHDI major
device IDs per SCSI Driver bus.


Module Restrictions
-------------------

Modules do not have regular access to filesystems on mass storage devices,
because HDDRIVER has not been launched yet at the time of module execution.
Modules are *not* meant to be replacements for programs that can simply be
launched from the AUTO folder. They should only be used when it is required
to execute code as early as possible during the boot process, i.e. before
HDDRIVER.SYS.


  Uwe.Seimet@seimet.de