Skip to content
Branch: master
Find file History

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
MODSTART.H Updated READMEs, added sample module, improved Pure C support Nov 7, 2019
MODSTART.PRJ
MODSTART.S
README
SAMPLE.C Updated module README Feb 18, 2020
SAMPLE.PRJ

README

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

HDDRIVER 11 supports starting programs, so-called HDDRIVER modules, early
during the boot sequence before the actual driver HDDRIVER.SYS. The main
difference of modules and AUTO folder programs is that a module is
launched *before* HDDRIVER.SYS, an AUTO folder program	is launched *after*
HDDRIVER.SYS. A typical module provides functionality HDDRIVER can make
use of during the boot sequence, e.g. a SCSI Driver, which provides access
to a non-standard bus. For some programs it can be useful that they can be
launched both ways, as a module and from the AUTO folder.
During the boot sequence HDDRIVER.SYS scans all available buses for devices,
so that any mass storage device supported by a SCSI Driver can fully 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.
HDDRIVER maps an 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 Execution
----------------

Like HDDRIVER.SYS modules are located in the root directory of the boot
partition. They run in the same type of RAM (ST-RAM or TT-RAM) as
HDDRIVER.SYS, depending on the HDDRIVER installation settings of HDDRUTIL.
Module filenames must 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) 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, any remaining modules are skipped and HDDRIVER.SYS is
executed next.
Modules are always run in supervisor mode.


C Modules
---------

Depending on its functionality it may be useful to be able to launch the
same binary either from the AUTO folder or as an HDDRIVER 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 (e.g. before
PCSTART) to the Pure C project file you are building your program with.
The MODSTART startup code automatically detects whether the binary was
started by TOS or as an HDDRIVER module.
Modules implemented in C (using MODSTART) must terminate with Pterm0(),
Pterm() or Ptermres(). 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 started as a
module isHddriverModule() declared in HDDRMOD.H can be called.


Assembler Modules
-----------------

Modules implemented in assembler are launched by calling their start
address + 4. They have to free any unused memory and must terminate with
RTS. They must not execute any Pterm*() call.
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
-------------

SAMPLE.C implements a simple HDDRIVER module, which is aware of whether	it
was started as a regular program or as a module.


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

- Modules do not have regular access to filesystems on mass storage
  devices, because HDDRIVER has not been initialized yet at the time of
  module execution.
- MODSTART.S and SAMPLE.C should be studied in order to learn more about
  HDDRIVER modules.

Modules are not meant to be replacements for programs that can simply be
launched from within 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, 2020-02-18
You can’t perform that action at this time.