Copyright (c) Hyperion Entertainment and contributors.
Expansion Library
|
This page is not yet fully updated to AmigaOS 4.x some of the information contained here may not be applicable in part or totally. |
Contents
Expansion Library
Amiga RAM expansion boards and other expansion bus peripherals are designed to reside at dynamically assigned address spaces within the system. The configuration and initialization of these expansion peripherals is performed by the expansion.library.
AUTOCONFIG
The Amiga AUTOCONFIG protocol is designed to allow the dynamic assignment of available address space to expansion boards, eliminating the need for user configuration via jumpers. Such expansion boards include memory boards, hard disk controllers, network interfaces, and other special purpose expansion devices. Some expansion devices, such as RAM boards, require no special driver software. Other types of expansion devices may use a disk-loaded driver from the "DEVS:" or "SYS:Expansion drawer", or an on-board ROM driver (for example, a self-booting hard disk controller).
This chapter will concentrate on the software and driver side of Zorro expansion devices, using a Zorro-II device as an example. Zorro-III devices have additional identifying bits and memory size options which are described in the Zorro-III hardware documentation. For more information on Zorro-II and Zorro-III expansion hardware, see the "Zorro Expansion Bus" appendix of the Amiga Hardware Reference Manual, 3rd Edition. For additional information specific to Zorro-II boards, see the A500/A2000 Technical Reference Manual.
AUTOCONFIG occurs whenever the Amiga is powered on or reset. During early system initialization, expansion.library identifies the expansion boards that are installed in the Amiga and dynamically assigns an appropriate address range for each board to reside at. During this AUTOCONFIG process, each expansion board first appears in turn at $E80000 (Zorro-II) or $FF000000 (Zorro-III), presenting readable identification information, generally in a PAL or a ROM, at the beginning of the board. The identification includes the size of the board, its address space preferences, type of board (memory or other), and a unique Hardware Manufacturer Number assigned by the AmigaOS development team.
The unique Hardware Manufacturer number, in combination with a vendor-supplied product number, provides a way for boards to be identified and for disk-based drivers to be matched with expansion boards. All expansion boards for the Amiga must implement the AUTOCONFIG protocol.
The Expansion Sequence
During system initialization, expansion.library configures each expansion peripheral in turn by examining its identification information and assigning it an appropriate address space. If the board is a RAM board, it can be added to the system memory list to make the RAM available for allocation by system tasks.
Descriptions of all configured boards are kept in a private ExpansionBase list of ConfigDev structures. A board's identification information is stored in the ExpansionRom sub-structure contained within the ConfigDev structure. Applications can examine individual or all ConfigDev structures with the expansion.library function FindConfigDev().
The ConfigDev structure is defined in <libraries/configvars.h>:
struct ConfigDev { struct Node cd_Node; UBYTE cd_Flags; /* (read/write) */ UBYTE cd_Pad; /* reserved */ struct ExpansionRom cd_Rom; /* copy of board's expansion ROM */ APTR cd_BoardAddr; /* where in memory the board was placed */ ULONG cd_BoardSize; /* size of board in bytes */ UWORD cd_SlotAddr; /* which slot number (PRIVATE) */ UWORD cd_SlotSize; /* number of slots (PRIVATE) */ APTR cd_Driver; /* pointer to node of driver */ struct ConfigDev *cd_NextCD; /* linked list of drivers to config */ ULONG cd_Unused[4]; /* for whatever the driver wants */ }; /* cd_Flags */ #define CDB_SHUTUP 0 /* this board has been shut up */ #define CDB_CONFIGME 1 /* this board needs a driver to claim it */ #define CDF_SHUTUP 0x01 #define CDF_CONFIGME 0x02
The ExpansionRom structure within ConfigDev contains the board identification information that is read from the board's PAL or ROM at expansion time. The actual onboard identification information of a Zorro-II board appears in the high nibbles of the first $40 words at the start of the board. Except for the first nibble pair ($00/$02) which when combined form er_Type, the information is stored in inverted ("ones-complement") format where binary 1's are represented as 0's and 0's are represented as 1's. The expansion.library reads the nibbles of expansion information from the board, un-inverts them (except for $00/$02 er_Type which is already un-inverted), and combines them to form the elements of the ExpansionRom structure.
The ExpansionRom structure is defined in <libraries/configregs.h>:
struct ExpansionRom { /* First 16 bytes of the expansion ROM */ UBYTE er_Type; /* Board type, size and flags */ UBYTE er_Product; /* Product number, assigned by manufacturer */ UBYTE er_Flags; /* Flags */ UBYTE er_Reserved03; /* Must be zero ($ff inverted) */ UWORD er_Manufacturer; /* Unique ID,ASSIGNED BY AmigaOS development team */ ULONG er_SerialNumber; /* Available for use by manufacturer */ UWORD er_InitDiagVec; /* Offset to optional "DiagArea" structure */ UBYTE er_Reserved0c; UBYTE er_Reserved0d; UBYTE er_Reserved0e; UBYTE er_Reserved0f; };
Simple Expansion Library Example
The following example uses FindConfigDev() to print out information about all of the configured expansion peripherals in the system. FindConfigDev() searches the system's list of ConfigDev structures and returns a pointer to the ConfigDev structure matching a specified board:
newconfigdev = struct ConfigDev *FindConfigDev( struct ConfigDev *oldconfigdev,
LONG manufacturer, LONG product )
The oldconfigdev argument may be set to NULL to begin searching at the top of the system list or, if it points to a valid ConfigDev, searching will begin after that entry in the system list. The manufacturer and product arguments can be set to search for a specific manufacturer and product by number, or, if these are set to -1, the function will match any board.
;/* findboards.c - Execute me to compile me with SAS C 5.10
LC -b1 -cfistq -v -y -j73 findboards.c
Blink FROM LIB:c.o,findboards.o TO findboards LIBRARY LIB:LC.lib,LIB:Amiga.lib
quit
*/
#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/configvars.h>
#include <clib/exec_protos.h>
#include <clib/expansion_protos.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); } /* really */
#endif
struct Library *ExpansionBase = NULL;
void main(int argc, char **argv)
{
struct ConfigDev *myCD;
UWORD m,i;
UBYTE p,f,t;
if((ExpansionBase=OpenLibrary("expansion.library",0L))==NULL)
exit(RETURN_FAIL);
/*--------------------------------------------------*/
/* FindConfigDev(oldConfigDev,manufacturer,product) */
/* oldConfigDev = NULL for the top of the list */
/* manufacturer = -1 for any manufacturer */
/* product = -1 for any product */
/*--------------------------------------------------*/
myCD = NULL;
while(myCD=FindConfigDev(myCD,-1L,-1L)) /* search for all ConfigDevs */
{
printf("\n---ConfigDev structure found at location $%lx---\n",myCD);
/* These values were read directly from the board at expansion time */
printf("Board ID (ExpansionRom) information:\n");
t = myCD->cd_Rom.er_Type;
m = myCD->cd_Rom.er_Manufacturer;
p = myCD->cd_Rom.er_Product;
f = myCD->cd_Rom.er_Flags;
i = myCD->cd_Rom.er_InitDiagVec;
printf("er_Manufacturer =%d=$%04x=(~$%4x)\n",m,m,(UWORD)~m);
printf("er_Product =%d=$%02x=(~$%2x)\n",p,p,(UBYTE)~p);
printf("er_Type =$%02x",myCD->cd_Rom.er_Type);
if(myCD->cd_Rom.er_Type & ERTF_MEMLIST)
printf(" (Adds memory to free list)\n");
else printf("\n");
printf("er_Flags =$%02x=(~$%2x)\n",f,(UBYTE)~f);
printf("er_InitDiagVec =$%04x=(~$%4x)\n",i,(UWORD)~i);
/* These values are generated when the AUTOCONFIG(tm) software
* relocates the board
*/
printf("Configuration (ConfigDev) information:\n");
printf("cd_BoardAddr =$%lx\n",myCD->cd_BoardAddr);
printf("cd_BoardSize =$%lx (%ldK)\n",
myCD->cd_BoardSize,((ULONG)myCD->cd_BoardSize)/1024);
printf("cd_Flags =$%x",myCD->cd_Flags);
if(myCD->cd_Flags & CDF_CONFIGME)
printf("\n");
else printf(" (driver clears CONFIGME bit)\n");
}
CloseLibrary(ExpansionBase);
}
Expansion Board Drivers
The Amiga operating system contains support for matching up disk-based drivers with AUTOCONFIG boards. Though such drivers are commonly Exec devices, this is not required. The driver may, for instance, be an Exec library or task. The system software also supports the initialization of onboard ROM driver software.
Disk Based Drivers
Disk-based expansion board drivers and their icons are generally placed in the "SYS:Expansion" drawer of the user's "SYS:" disk or partition. The icon Tool Type field must contain the unique Hardware Manufacturer number, and the Product number of the expansion board(s) the driver is written for. (For more about icon Tool Type fields refer to Icon Library.)
The "BindDrivers" command issued during the disk startup-sequence attempts to match disk-based drivers with their expansion boards. To do this, "BindDrivers" looks in the Tool Types field of all icon files in "SYS:Expansion". If the Tool Type "PRODUCT" is found in the icon, then this is an icon file for a driver. "BindDrivers" will then attempt to match the manufacturer and product number in this PRODUCT Tool Type with those of a board that was configured at expansion time.
For example, suppose you are manufacturer #1019. You have two products, #1 and #2 which both use the same driver. The icon for your driver for these two products would have a Tool Type set to "PRODUCT=1019/1|1019/2". This means: I am an icon for a driver that works with product number 1 or 2 from manufacturer 1019, now bind me. Spaces are not legal. Here are two other examples:
| PRODUCT=1208/11 | is the Tool Type for a driver for product 11 from manufacturer number 1208. |
| PRODUCT=1017 | is the Tool Type for a driver for any product from manufacturer number 1017. |
If a matching board is found for the disk-based driver, the driver code is loaded and then initialized with the Exec InitResident() function. From within its initialization code, the driver can get information about the board it is bound to by calling the expansion.library function GetCurrentBinding(). This function will provide the driver with a copy of a CurrentBinding structure, including a pointer to a ConfigDev structure (possibly linked to additional ConfigDevs via the cd_NextCD field) of the expansion board(s) that matched the manufacturer and product IDs.
/* this structure is used by GetCurrentBinding() and SetCurrentBinding() */
struct CurrentBinding {
struct ConfigDev *cb_ConfigDev; /* first configdev in chain */
UBYTE * cb_FileName; /* file name of driver */
UBYTE * cb_ProductString; /* product # string */
UBYTE ** cb_ToolTypes; /* tooltypes from disk object */
};
GetCurrentBinding() allows the driver to find out the base address and other information about its board(s). The driver must unset the CONFIGME bit in the cd_Flags field of the ConfigDev structure for each board it intends to drive, and record the driver's Exec node pointer in the cd_Driver structure. This node should contain the LN_NAME and LN_TYPE (i.e., NT_DEVICE, NT_TASK, etc.) of the driver.
| Important Note |
|---|
| The GetCurrentBinding() function, and driver binding in general, must be bracketed by an ObtainConfigBinding() and ReleaseConfigBinding() semaphore. The "BindDrivers" command obtains this semaphore and performs a SetCurrentBinding() before calling InitResident(), allowing the driver to simply do a GetCurrentBinding(). |
Full source code for a disk-based Expansion or "DEVS:" sample device driver may be found in Example Device. Autodocs for expansion.library functions may be found in the SDK.
Expansion Drivers and DOS
Two other expansion.library functions commonly used by expansion board drivers are MakeDosNode() and AddDosNode(). These functions allow a driver to create and add a DOS device node (for example "DH0:") to the system. AddBootNode() can be used to add an autobooting DOS device node.
MakeDosNode() requires an initialized structure of environment information for creating a DOS device node. The format of the function is:
struct DeviceNode *deviceNode = MakeDosNode(parameterPkt);
The parameterPkt argument is a pointer to an initialized packet of environment parameters.
The parameter packet for MakeDosNode() consists of four longwords followed by a DosEnvec structure:
;-----------------------------------------------------------------------
;
; Layout of parameter packet for MakeDosNode
;
;-----------------------------------------------------------------------
* The packet for MakeDosNode starts with the following four
* longwords, directly followed by a DosEnvec structure.
APTR dosName ; Points to a DOS device name (ex. 'RAM1',0)
APTR execName ; Points to device driver name (ex. 'ram.device',0)
ULONG unit ; Unit number
ULONG flags ; OpenDevice flags
* The DosEnvec disk "environment" is a longword array that describes the
* disk geometry. It is variable sized, with the length at the beginning.
* Here are the constants for a standard geometry.
* See libraries/filehandler.i for additional notes.
STRUCTURE DosEnvec,0
ULONG de_TableSize ; Size of Environment vector
ULONG de_SizeBlock ; in longwords: standard value is 128
ULONG de_SecOrg ; not used; must be 0
ULONG de_Surfaces ; # of heads (surfaces). drive specific
ULONG de_SectorPerBlock ; not used; must be 1
ULONG de_BlocksPerTrack ; blocks per track. drive specific
ULONG de_Reserved ; DOS reserved blocks at start of partition.
ULONG de_PreAlloc ; DOS reserved blocks at end of partition
ULONG de_Interleave ; usually 0
ULONG de_LowCyl ; starting cylinder. typically 0
ULONG de_HighCyl ; max cylinder. drive specific
ULONG de_NumBuffers ; Initial # DOS of buffers.
ULONG de_BufMemType ; type of mem to allocate for buffers
ULONG de_MaxTransfer ; Max number of bytes to transfer at a time
ULONG de_Mask ; Address Mask to block out certain memory
LONG de_BootPri ; Boot priority for autoboot
ULONG de_DosType ; ASCII (HEX) string showing file system type;
; 0X444F5300 is old file system,
; 0X444F5301 is fast file system
ULONG de_Baud ; Baud rate for serial handler
ULONG de_Control ; Control word for handler/file system
; (used as file system/handler desires)
ULONG de_BootBlocks ; Number of blocks containing boot code
; (for non-AmigaDOS file systems)
LABEL DosEnvec_SIZEOF
After making a DOS device node, drivers (except for autoboot drivers) use AddDosNode(deviceNode) to add their node to the system. Autoboot drivers will instead use the AddBootNode() function to add a BootNode to the ExpansionBase.eb_MountList.
ROM Based and Autoboot Drivers
The system software supports the initialization of ROM drivers residing on expansion peripherals, including the ability for drivers to provide a DOS node which the system can boot from. This feature is known as Autoboot.
Automatic boot from a ROM-equipped expansion board is accomplished before DOS is initialized. This facility makes it possible to automatically boot from a hard disk without any floppy disks inserted. Likewise, it is possible to automatically boot from any device which supports the ROM protocol, even allowing the initialization of a disk operating system other than the Amiga's dos.library. ROM-based drivers contain several special entry points that are called at different stages of system initialization. These three stages are known as DIAG, ROMTAG INIT and BOOT.
Events At DIAG Time
When your AUTOCONFIG hardware board is configured by the expansion initialization routine, its ExpansionRom structure is copied into the ExpansionRom subfield of a ConfigDev structure. This ConfigDev structure will be linked to the expansion.library's private list of configured boards.
After the board is configured, the er_Type field of its ExpansionRom structure is checked. The DIAGVALID bit set declares that there is a valid DiagArea (a ROM/diagnostic area) on this board. If there is a valid DiagArea, expansion next tests the er_InitDiagVec vector in its copy of the ExpansionRom structure. This offset is added to the base address of the configured board; the resulting address points to the start of this board's DiagArea.
struct ExpansionRom { UBYTE er_Type; /* <-- if ERTB_DIAGVALID set */ UBYTE er_Product; UBYTE er_Flags; UBYTE er_Reserved03; UWORD er_Manufacturer; ULONG er_SerialNumber; UWORD er_InitDiagVec; /* <-- then er_InitDiagVec */ UBYTE er_Reserved0c; /* is added to cd_BoardAddr */ UBYTE er_Reserved0d; /* and points to DiagArea */ UBYTE er_Reserved0e; UBYTE er_Reserved0f; };
Now expansion knows that there is a DiagArea, and knows where it is.
struct DiagArea { UBYTE da_Config; /* <-- if DAC_CONFIGTIME is set */ UBYTE da_Flags; UWORD da_Size; /* <-- then da_Size bytes will */ UWORD da_DiagPoint; /* be copied into RAM */ UWORD da_BootPoint; UWORD da_Name; UWORD da_Reserved01; UWORD da_Reserved02; }; /* da_Config definitions */ #define DAC_BUSWIDTH 0xC0 /* two bits for bus width */ #define DAC_NIBBLEWIDE 0x00 #define DAC_BYTEWIDE 0x40 /* invalid for 1.3 - see note below */ #define DAC_WORDWIDE 0x80 #define DAC_BOOTTIME 0x30 /* two bits for when to boot */ #define DAC_NEVER 0x00 /* obvious */ #define DAC_CONFIGTIME 0x10 /* call da_BootPoint when first configuring the device */ #define DAC_BINDTIME 0x20 /* run when binding drivers to boards */
Next, expansion tests the first byte of the DiagArea structure to determine if the CONFIGTIME bit is set. If this bit is set, it checks the da_BootPoint offset vector to make sure that a valid bootstrap routine exists. If so, expansion copies da_Size bytes into RAM memory, starting at beginning of the DiagArea structure.
The copy will include the DiagArea structure itself, and typically will also include the da_DiagPoint ROM/diagnostic routine, a Resident structure (romtag), a device driver (or at least the device initialization tables or structures which need patching), and the da_BootPoint routine. In addition, the BootNode and parameter packet for MakeDosNode() may be included in the copy area for Diag-time patching. Strings such as DOS and Exec device names, library names, and the romtag ID string may also be included in the copy area so that both position-independent ROM code and position-independent routines in the copy area may reference them PC relative.
The copy will be made either nibblewise, or wordwise, according to the BUSWIDTH subfield of da_Config. Note that the da_BootPoint offset must be non-NULL, or else no copy will occur.
The following illustrates an example Diag copy area, and specifies the various fields which should be coded as relative offsets for later patching by your DiagPoint routine.
Example DiagArea Copy in RAM
DiagStart: ; a struct DiagArea
CCFF ; da_Config, da_Flags
SIZE ; da_Size - coded as EndCopy-DiagStart
DIAG ; da_DiagPoint - coded as DiagEntry-DiagStart
BOOT ; da_BootPoint - coded as BootEntry-DiagStart
NAME ; da_Name - coded as DevName-DiagStart
0000 ; da_Reserved01 - Above fields above are supposed
0000 ; da_Reserved02 to be relative. No patching needed
Romtag: rrrr ; a struct Resident (``Romtag'')
... RT_MATCHTAG, RT_ENDSKIP, RT_NAME and RT_IDSTRING
... addresses are coded relatively as label-DiagStart.
... The RT_INIT vector is coded as a relative offset
... from the start of the ROM. DiagEntry patches these.
DevName: ssss..0 ; The name string for the exec device
IdString: iiii..0 ; The ID string for the Romtag
BootEntry: BBBB ; Boot-time code
...
DiagEntry: DDDD ; Diag-time code (position independent)
... When called, performs patching of the relative-
coded addresses which need to be absolute.
OtherData:
dddd ; Device node or structs/tables (patch names, vectors)
bbbb ; BootNode (patch ln_Name and bn_DeviceNode)
pppp ; MakeDosNode packet (patch dos and exec names)
ssss ; other name, ID, and library name strings
...
EndCopy:
Now the ROM "image" exists in RAM memory. Expansion stores the ULONG address of that "image" in the UBYTES er_Reserved0c, 0d, 0e and 0f. The address is stored with the most significant byte in er_Reserved0c, the next to most significant byte in er_Reserved0d, the next to least significant byte in er_Reserved0e, and the least significant byte in er_Reserved0f – i.e., it is stored as a longword at the address er_Reserved0c.
Expansion finally checks the da_DiagPoint offset vector, and if valid executes the ROM/diagnostic routine contained as part of the ROM "image". This diagnostic routine is responsible for patching the ROM image so that required absolute addresses are relocated to reflect the actual location of code and strings, as well as performing any diagnostic functions essential to the operation of its associated AUTOCONFIG board. The structures which require patching are located within the copy area so that they can be patched at this time. Patching is required because many of the structures involved require absolute pointers to such things as name strings and code, but the absolute locations of the board and the RAM copy area are not known when code the structures.
The patching may be accomplished by coding pointers which require absolute addresses instead as relative offsets from either the start of the DiagArea structure, or the start of the board's ROM (depending on whether the final absolute pointer will point to a RAM or ROM location). The Diag routine is passed both the actual base address of the board, and the address of the Diag copy area in RAM. The routine can then patch the structures in the Diag copy area by adding the appropriate address to resolve each pointer.
Example DiagArea and Diag patching routine:
**
** Sample autoboot code fragment
**
** These are the calling conventions for the Diag routine
**
** A7 -- points to at least 2K of stack
** A6 -- ExecBase
** A5 -- ExpansionBase
** A3 -- your board's ConfigDev structure
** A2 -- Base of diag/init area that was copied
** A0 -- Base of your board
**
** Your Diag routine should return a non-zero value in D0 for success.
** If this value is NULL, then the diag/init area that was copied
** will be returned to the free memory pool.
**
INCLUDE "exec/types.i"
INCLUDE "exec/nodes.i"
INCLUDE "exec/resident.i"
INCLUDE "libraries/configvars.i"
; LVO's resolved by linking with library amiga.lib
XREF _LVOFindResident
ROMINFO EQU 1
ROMOFFS EQU $0
* ROMINFO defines whether you want the AUTOCONFIG information in
* the beginning of your ROM (set to 0 if you instead have PALS
* providing the AUTOCONFIG information instead)
*
* ROMOFFS is the offset from your board base where your ROMs appear.
* Your ROMs might appear at offset 0 and contain your AUTOCONFIG
* information in the high nibbles of the first $40 words ($80 bytes).
* Or, your autoconfig ID information may be in a PAL, with your
* ROMs possibly being addressed at some offset (for example $2000)
* from your board base. This ROMOFFS constant will be used as an
* additional offset from your configured board address when patching
* structures which require absolute pointers to ROM code or data.
*----- We'll store Version and Revision in serial number
VERSION EQU 37 ; also the high word of serial number
REVISION EQU 1 ; also the low word of serial number
* See the Amiga Hardware Manual for more info.
MANUF_ID EQU 2011 ; CBM assigned (2011 for hackers only)
PRODUCT_ID EQU 1 ; Manufacturer picks product ID
BOARDSIZE EQU $40000 ; How much address space board decodes
SIZE_FLAG EQU 3 ; Autoconfig 3-bit flag for BOARDSIZE
; 0=$800000(8meg) 4=$80000(512K)
; 1=$10000(64K) 5=$100000(1meg)
; 2=$20000(128K) 6=$200000(2meg)
; 3=$40000(256K) 7=$400000(4meg)
CODE
******* RomStart ***************************************************
**********************************************************************
RomStart:
IFGT ROMINFO
;
; ExpansionRom structure
;
; Note - If you implement your ExpansionRom and ExpansionControl
; with PALS, then you can comment out everything until DiagStart:
; (ie. Make ROMID EQU 0)
* ; High nibbles of first two words ($00,$02) are er_Type (not inverted)
; er_Type
dc.w $D000 ; 11xx normal board type
; xx0x not in memory free list
; xxx1 Diag valid (has driver)
dc.w (SIZE_FLAG<<12)&$7000 ; 0xxx not chained
; xnnn flags board size
* ; High nibbles of next two words are er_Product
* ; These are inverted (~), as are all other words except $40 and $42
; er_Product
dc.w (~(PRODUCT_ID<<8))&$f000,(~(PRODUCT_ID<<12))&$f000
; er_Flags
dc.w (~$C000)&$f000 ; ~1xxx board is moveable
; ~x1xx board can't be shut up
dc.w (~0)&$f000 ;
dc.w (~0)&$f000,(~0)&$f000 ; er_Reserved03
; er_Manufacturer
dc.w (~(MANUF_ID))&$f000,(~(MANUF_ID<<4))&$f000
dc.w (~(MANUF_ID<<8))&$f000,(~(MANUF_ID<<12))&$f000
; er_SerialNumber
dc.w (~(VERSION))&$f000,(~(VERSION<<4))&$f000
dc.w (~(VERSION<<8))&$f000,(~(VERSION<<12))&$f000
dc.w (~(REVISION))&$f000,(~(REVISION<<4))&$f000
dc.w (~(REVISION<<8))&$f000,(~(REVISION<<12))&$f000
; er_InitDiagVec
dc.w (~((DiagStart-RomStart)))&$f000
dc.w (~((DiagStart-RomStart)<<4))&$f000
dc.w (~((DiagStart-RomStart)<<8))&$f000
dc.w (~((DiagStart-RomStart)<<12))&$f000
dc.w (~0)&$f000,(~0)&$f000 ; er_Reserved0c
dc.w (~0)&$f000,(~0)&$f000 ; er_Reserved0d
dc.w (~0)&$f000,(~0)&$f000 ; er_Reserved0e
dc.w (~0)&$f000,(~0)&$f000 ; er_Reserved0f
IFNE *-RomStart-$40
FAIL "ExpansionRom structure not the right size"
ENDC
;Note: nibbles $40 and $42 are not to be inverted
dc.w (0)&$f000,(0)&$f000 ; ec_Interrupt (no interrupts)
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved11
dc.w (~0)&$f000,(~0)&$f000 ; ec_BaseAddress (write only)
dc.w (~0)&$f000,(~0)&$f000 ; ec_Shutup (write only)
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved14
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved15
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved16
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved17
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved18
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved19
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved1a
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved1b
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved1c
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved1d
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved1e
dc.w (~0)&$f000,(~0)&$f000 ; ec_Reserved1f
IFNE *-RomStart-$80
FAIL "Expansion Control structure not the right size"
ENDC
ENDC ;ROMINFO
******* DiagStart **************************************************
DiagStart: ; This is the DiagArea structure whose relative offset from
; your board base appears as the Init Diag vector in your
; autoconfig ID information. This structure is designed
; to use all relative pointers (no patching needed).
dc.b DAC_WORDWIDE+DAC_CONFIGTIME ; da_Config
dc.b 0 ; da_Flags
dc.w EndCopy-DiagStart ; da_Size
dc.w DiagEntry-DiagStart ; da_DiagPoint
dc.w BootEntry-DiagStart ; da_BootPoint
dc.w DevName-DiagStart ; da_Name
dc.w 0 ; da_Reserved01
dc.w 0 ; da_Reserved02
******* Resident Structure *****************************************
Romtag:
dc.w RTC_MATCHWORD ; UWORD RT_MATCHWORD
rt_Match: dc.l Romtag-DiagStart ; APTR RT_MATCHTAG
rt_End: dc.l EndCopy-DiagStart ; APTR RT_ENDSKIP
dc.b RTW_COLDSTART ; UBYTE RT_FLAGS
dc.b VERSION ; UBYTE RT_VERSION
dc.b NT_DEVICE ; UBYTE RT_TYPE
dc.b 20 ; BYTE RT_PRI
rt_Name: dc.l DevName-DiagStart ; APTR RT_NAME
rt_Id: dc.l IdString-DiagStart ; APTR RT_IDSTRING
rt_Init: dc.l Init-RomStart ; APTR RT_INIT
******* Strings referenced in Diag Copy area ************************
DevName: dc.b 'abc.device',0 ; Name string
IdString dc.b 'abc ',48+VERSION,'.',48+REVISION ; Id string
DosName: dc.b 'dos.library',0 ; DOS library name
DosDevName: dc.b 'ABC',0 ; dos device name for MakeDosNode()
; (dos device will be ABC:)
ds.w 0 ; word align
******* DiagEntry **************************************************
**********************************************************************
*
* success = DiagEntry(BoardBase,DiagCopy, configDev)
* d0 a0 a2 a3
*
* Called by expansion architecture to relocate any pointers
* in the copied diagnostic area. We will patch the romtag.
* If you have pre-coded your MakeDosNode packet, BootNode,
* or device initialization structures, they would also need
* to be within this copy area, and patched by this routine.
*
**********************************************************************
DiagEntry:
lea patchTable-RomStart(a0),a1 ; find patch table
adda.l #ROMOFFS,a1 ; adjusting for ROMOFFS
* Patch relative pointers to labels within DiagCopy area
* by adding Diag RAM copy address. These pointers were coded as
* long relative offsets from base of the DiagArea structure.
*
dpatches:
move.l a2,d1 ;d1=base of ram Diag copy
dloop:
move.w (a1)+,d0 ;d0=word offs. into Diag needing patch
bmi.s bpatches ;-1 is end of word patch offset table
add.l d1,0(a2,d0.w) ;add DiagCopy addr to coded rel. offset
bra.s dloop
* Patches relative pointers to labels within the ROM by adding
* the board base address + ROMOFFS. These pointers were coded as
* long relative offsets from RomStart.
*
bpatches:
move.l a0,d1 ;d1 = board base address
add.l #ROMOFFS,d1 ;add offset to where your ROMs are
rloop:
move.w (a1)+,d0 ;d0=word offs. into Diag needing patch
bmi.s endpatches ;-1 is end of patch offset table
add.l d1,0(a2,d0.w) ;add ROM address to coded relative offset
bra.s rloop
endpatches:
moveq.l #1,d0 ; indicate "success"
rts
******* BootEntry **************************************************
**********************************************************************
BootEntry: lea DosName(PC),a1 ; 'dos.library',0
jsr _LVOFindResident(a6) ; find the DOS resident tag
move.l d0,a0 ; in order to bootstrap
move.l RT_INIT(A0),a0 ; set vector to DOS INIT
jsr (a0) ; and initialize DOS
rts
*
* End of the Diag copy area which is copied to RAM
*
EndCopy:
*************************************************************************
*************************************************************************
*
* Beginning of ROM driver code and data that is accessed only in
* the ROM space. This must all be position-independent.
*
patchTable:
* Word offsets into Diag area where pointers need Diag copy address added
dc.w rt_Match-DiagStart
dc.w rt_End-DiagStart
dc.w rt_Name-DiagStart
dc.w rt_Id-DiagStart
dc.w -1
* Word offsets into Diag area where pointers need boardbase+ROMOFFS added
dc.w rt_Init-DiagStart
dc.w -1
******* Romtag InitEntry **********************************************
*************************************************************************
Init: ; After Diag patching, our romtag will point to this
; routine in ROM so that it can be called at Resident
; initialization time.
; This routine will be similar to a normal expansion device
; initialization routine, but will MakeDosNode then set up a
; BootNode, and Enqueue() on eb_MountList.
;
rts
; Rest of your position-independent device code goes here.
END
Your da_DiagPoint ROM/diagnostic routine should return a non-zero value to indicate success; otherwise the ROM "image" will be unloaded from memory, and its address will be replaced with NULL bytes in locations er_Reserved0c, 0d, 0e and 0f.
Now that the ROM "image" has been copied into RAM, validated, and linked to board's ConfigDev structure, the expansion module is free to configure all other boards on the utility.library's private list of boards.
It may help to see just how a card's ROM AUTOCONFIG information corresponds to the ExpansionRom structure. This chart shows the contents of on-card memory for a fictional expansion card. Note that the ExpansionRom.Flags field ($3F in addresses $08/$0A below) is shown interpreted in its inverted form of $3F. Once the value is uninverted to become $C0, you should use the #defines in <libraries/configregs.h> to interpret it.
Sample Zorro-II AUTOCONFIG ROM Information Viewed as a Hex Dump
FLAG AND FIELD DEFINITIONS THIS BOARD
-----------------------------------------------------------------
1xxx chained 11 = Normal type
x111 size Don't addmem
000=8meg,001=64K,010=128K,etc. ROM Vector Valid
11xx type / 1xxx nopref Not chained
xx1x addmem / x1xx canshut Size 256K
xxx1 ROM / xx11 reserved Product#=~$FE=1
\ / ~Prod# / Flags=~$3F=$C0
\ / / \ / res. reserved Prefer exp space
0000: D0003000 F000E000 3000F000 F000F000 Can't be shut up
-----------------------------------------------------------------
~Manufacturer# ~HiWord Serial# Manu#=~$F824=$7DB=2011
/ / \ \ / / \ \ HiSer=~$FFDA=$0025=37
0010: F0008000 20004000 F000F000 D000A000
-----------------------------------------------------------------
~LoWord Serial# ~Rom Vector LoSer=~$FFFE=$0001=1
/ / \ \ / / \ \ Rom Vector=~$FF7F=$80
0020: F000F000 F000E000 F000F000 7000F000 from board base
-----------------------------------------------------------------
The AUTOCONFIG information from the above card would appear as follows in an ExpansionRom structure:
| Nibble Pairs | ExpansionRom Field | Value |
|---|---|---|
| 00/02 | er_Type | $D3 |
| 04/06 | er_Product | $01 = 1 |
| 08/0A | er_Flags | $C0 |
| 10/12 and 14/16 | er_Manufacturer | $07DB = 2011 |
| 18/1A thru 24/26 | er_SerialNumber | $00250001 |
| 28/2A and 2C/2E | er_InitDiagVec | $0080 |
If a card contains a ROM driver (Rom Vector valid), and the vector is at offset $80 (as in this example) the DiagArea structure will appear at offset $0080 from the base address of the board. This example card’s Resident structure (romtag) directly follows its DiagArea structure.
WORDWIDE+CONFIGTIME ROMTAG
\ flags DiagPt Devname starts
\ \ DAsize / BootPt / here DiagPt, BootPt,
\ \ /\ /\ /\ /\ res. res. /\ DevName relative
0080: 90000088 004A0076 00280000 00004AFC to Diag struct
-----------------------------------------------------------------
COLDSTART NT_DEVICE backptr,endskip,
\ ver /priority and DevName coded
backptr endskip \ \ / / DevName relative, patched
0090: 0000000E 00000088 01250314 00000028 at Diag time
-----------------------------------------------------------------
ID and InitEntry
IDstring InitEntry coded relative,
00A0: 00000033 00000116 patched at Diag
-----------------------------------------------------------------
Events At ROMTAG INIT Time
Next, most resident system modules (for example graphics) are initialized. As part of the system initialization procedure a search is made of the expansion.library's private list of boards (which contains a ConfigDev structure for each of the AUTOCONFIG hardware boards). If the cd_Flags specify CONFIGME and the er_Type specifies DIAGVALID, the system initialization will do three things:
First, it will set the current ConfigDev as the current binding (see the expansion.library SetCurrentBinding() function). Second, it will check the DiagArea's da_Config flag to make sure that the CONFIGTIME bit is set. Third, it will search the ROM "image" associated with this hardware board for a valid Resident structure (<exec/resident.h>); and, if one is located, will call InitResident() on it, passing a NULL segment list pointer as part of the call.
Next, the board's device driver is initialized. The Resident structure associated with this board's device driver (which has now been patched by the ROM/diagnostic routine) should follow standard system conventions in initializing the device driver provided in the boot ROMs. This driver should obtain the address of its associated ConfigDev structure via GetCurrentBinding().
Once the driver is initialized, it is responsible for some further steps. It must clear the CONFIGME bit in the cd_Flags of its ConfigDev structure, so that the system knows not to configure this device again if "BindDrivers" is run after bootstrap. Also, though it is not currently mandatory, the driver should place a pointer to its Exec node in the cd_Driver field of the ConfigDev structure. This will generally be a device (NT_DEVICE) node. And for this device to be bootable, the driver must create a BootNode structure, and link this BootNode onto the expansion.library's eb_MountList.
The BootNode structure (see <libraries/expansionbase.h>) contains a Node of the new type NT_BOOTNODE (see <exec/nodes.h>). The driver must initialize the ln_Name field to point to the ConfigDev structure which it has obtained via the GetCurrentBinding() call. The bn_Flags subfield is currently unused and should be initialized to NULL. The bn_DeviceNode must be initialized to point to the DosNode for the device.
When the DOS is initialized later, it will attempt to boot from the first BootNode on the eb_MountList. The eb_MountList is a priority sorted List, with nodes of the highest priority at the head of the List. For this reason, the device driver must enqueue a BootNode onto the list using the Exec library function Enqueue().
<In the case of an autoboot of AmigaDOS, the BootNode must be linked to a DeviceNode of the AmigaDOS type (see <libraries/filehandler.h>), which the driver can create via the expansion library MakeDosNode() function call. When the DOS "wakes up", it will attempt to boot from this DeviceNode.
Events At BOOT Time
If there is no boot disk in the internal floppy drive, the system strap module will call a routine to perform autoboot. It will examine the eb_MountList; find the highest priority BootNode structure at the head of the List; validate the BootNode; determine which ConfigDev is associated with this BootNode; find its DiagArea; and call its da_BootPoint function in the ROM "image" to bootstrap the appropriate DOS. Generally, the BootPoint code of a ROM driver will perform the same function as the boot code installed on a floppy disk, i.e., it will FindResident() the dos.library, and jump to its RT_INIT vector. The da_BootPoint call, if successful, should not return.
If a boot disk is in the internal floppy drive, the system strap will Enqueue() a BootNode on the eb_MountList for "DF0:" at the suggested priority (see the Autodoc for the expansion.library AddDosNode() function). Strap will then open AmigaDOS, overriding the autoboot. AmigaDOS will boot from the highest priority node on the eb_MountList which should, in this case, be "DF0:". Thus, games and other bootable floppy disks will still be able to obtain the system for their own use.
In the event that there is no boot disk in the internal floppy drive and there are no ROM bootable devices on the autoconfiguration chain, the system does the normal thing, asking the user to insert a Workbench disk, and waiting until its request is satisfied before proceeding.
RigidDiskBlock and Alternate File Systems
Through the use of RigidDiskBlock information and the FileSystem.resource, it is possible for an autoboot driver to have access to enough information to mount all of its device partitions and even load alternate file systems for use with these partitions.
The RigidDiskBlock specification (also known as "hardblocks") defines blocks of data that exist on a hard disk to describe that disk. These blocks are created or modified with an installation utility (such as the hard drive Prep utility for the A2090A ST506/SCSI controller card) provided by the disk controller manufacturer, and they are read and used by the device driver ROM (or expansion) code. They are not generally accessible to the user as they do not appear on any DOS device. The blocks are tagged with a unique identifier, checksummed, and linked together.
The five block types currently defined are RigidDiskBlock, BadBlockBlock, PartitionBlock, FileSysHeaderBlock, and LoadSegBlock.
The root of these blocks is the RigidDiskBlock. The RigidDiskBlock must exist on the disk within the first RDB_LOCATION_LIMIT (16) blocks. This inhibits the use of the first cylinder(s) in an AmigaDOS partition: although it is strictly possible to store the RigidDiskBlock data in the reserved area of a partition, this practice is discouraged since the reserved blocks of a partition are overwritten by Format, Install, DiskCopy, etc. The recommended disk layout, then, is to use the first cylinder(s) to store all the drive data specified by these blocks: i.e. partition descriptions, file system load images, drive bad block maps, spare blocks, etc. This allocation range is described in the RigidDiskBlock.
The RigidDiskBlock contains basic information about the configuration of the drive: number and size of blocks, tracks, and cylinders, as well as other relevant information. The RigidDiskBlock points to bad block, partition, file system and drive initialization description blocks.
The BadBlockBlock list contains a series of bad-block/good-block pairs. Each block contains as many as will fit in a physical sector on the drive. These mappings are to be handled by the driver on read and write requests.
The drive initialization description blocks are LoadSegBlocks that are loaded at boot time to perform drive-specific initialization. They are called with both C-style parameters on the stack, and assembler parameters in registers as follows:
d0 = DriveInit(lun, rdb, ior) (d0/a0/a1)
where lun is the SCSI logical unit number (needed to construct SCSI commands), rdb is a pointer to a memory copy of the RigidDiskBlock (which should not be altered), and ior is a standard IO request block that can be used to access the drive with synchronous DoIO() calls.
The result of DriveInit() is either -1, 0, or 1. A -1 signifies that an error occurred and drive initialization cannot continue. A 0 (zero) result reports success. In cases -1 and 0, the code is unloaded. A result of 1 reports success, and causes the code to be kept loaded. Furthermore, this resident code will be called whenever a reset is detected on the SCSI bus.
The FileSysHeaderBlock entries contain code for alternate file handlers to be used by partitions. There are several strategies that can be used to determine which of them to load. The most robust would scan all drives for those that are both required by partitions and have the highest fhb_Version, and load those. Whatever method is used, the loaded file handlers are added to the Exec resource FileSystem.resource, where they are used as needed to mount disk partitions.
The PartitionBlock entries contains most of the data necessary to add each partition to the system. They replace the Mount and "DEVS:MountList" mechanism for adding these partitions. The only items required by the expansion.library MakeDosNode() function which are not in this partition block are the Exec device name and unit, which is expected to be known by driver reading this information. The file system to be used is specified in the pb_Environment. If it is not the default file system (i.e., "DOS\0" or "DOS\1"), the node created by MakeDosNode() is modified as specified in a FileSystem.resource's FileSysEntry before adding it to the DOS list.
Only 512 byte blocks were supported by the pre-V36 file system, but this proposal was forward-looking by making the block size explicit, and by using only the first 256 bytes for all blocks but the LoadSeg and BadBlock data. Under the present file system, this allows using drives formatted with sectors 256 bytes or larger (i.e., 256, 512, 1024, etc). LoadSeg and BadBlock data use whatever space is available in a sector.
RigidDiskBlock
This is the current specification for the RigidDiskBlock:
- rdb_ID
- Set to "RDSK".
- rdb_SummedLongs
- Set to 64.
- rdb_ChkSum
- Block checksum (longword sum to zero).
- rdb_HostID
- SCSI Target ID of host.
- This is the initiator ID of the creator of this RigidDiskBlock. It is intended that modification of the RigidDiskBlock, or of any of the blocks pointed to by it, by another initiator (other than the one specified here) be allowed only after a suitable warning. The user is then expected to perform an audio lock out ("Hey, is anyone else setting up SCSI stuff on this bus?"). The rdb_HostID may become something other than the initiator ID when connected to a real network: that is an area for future standardization.
- rdb_BlockBytes
- Size of disk blocks.
- Present file system supports 256, 512, 1024, etc.
- rdb_Flags
- Long word of flags:
- RDBF._LAST
- No disks exist to be configured after this one on this controller (SCSI bus).
- RDBF._LASTLUN
- No LUNs exist to be configured greater than this one at this SCSI Target ID.
- RDBF._LASTTID
- No Target IDs exist to be configured greater than this one on this SCSI bus.
- RDBF._NORESELECT
- Don't bother trying to perform reselection when talking to this drive.
- RDBF._DISKID
- rdb_Disk... identification variables below contain valid data.
- RDBF._CTRLRID
- rdb_Controller... identification variables below contain valid data.
- RDBF._SYNCH
- Drive supports scsi synchronous mode; can be dangerous to use if it doesn't!
These fields point to other blocks on the disk which are not a part of any file system. All block pointers referred to are block numbers on the drive.
- rdb_BadBlockList
- Optional bad block list. A singly linked list of blocks of type PartitionBlock.
- rdb_PartitionList
- Optional first partition block. A singly linked list of blocks of type PartitionBlock.
- rdb_FileSysHeaderList
- Optional file system header block. A singly linked list of blocks of type FileSysHeaderBlock.
- rdb_DriveInit
- Optional drive-specific init code. A singly linked list of blocks of type LoadSegBlock containing initialization code. Called as DriveInit(lun,rdb,ior)(d0/a0/a1).
- rdb_Reserved1[6]
- Set to $FFFFFFFFs.
- These are reserved for future block lists. Since NULL for block lists is $FFFFFFFF, these reserved entries must be set to $FFFFFFFF.
These fields describe the physical layout of the drive.
- rdb_Cylinders
- Number of drive cylinders.
- rdb_Sectors
- Sectors per track.
- rdb_Heads
- Number of drive heads.
- rdb_Interleave
- Interleave.
- This drive interleave is independent from, and unknown to, the DOS’s understanding of interleave as set in the partition's environment vector.
- rdb_Park
- Landing zone cylinder.
- rdb_Reserved2[3]
- Set to zeros.
These fields are intended for ST506 disks. They are generally unused for SCSI devices and set to zero.
- rdb_WritePreComp
- Starting cylinder: write precompensation.
- rdb_ReducedWrite
- Starting cylinder: reduced write current.
- rdb_StepRate
- Drive step rate.
- rdb_Reserved3[5]
- Set to zeros.
These fields are used while partitions are set up to constrain the partitionable area and help describe the relationship between the drive's logical and physical layout.
- rdb_RDBlocksLo
- Low block of the range allocated for blocks described here. Replacement blocks for bad blocks may also live in this range.
- rdb_RDBlocksHi
- High block of this range (inclusive).
- rdb_LoCylinder
- Low cylinder of partitionable disk area.
- Blocks described by this include file will generally be found in cylinders below this one.
- rdb_HiCylinder
- High cylinder of partitionable data area.
- Usually rdb_Cylinders-1.
- rdb_CylBlocks
- Number of blocks available per cylinder.
- This may be rdb_Sectors*rdb_Heads, but a SCSI disk that, for example, reserves one block per cylinder for bad block mapping would use rdb_Sectors*rdb_Heads-1.
- rdb_AutoParkSeconds
- Number of seconds to wait before parking drive heads automatically. If zero, this feature is not desired.
- rdb_HighRDSKBlock
- Highest block used by these drive definitions.
- Must be less than or equal to rdb_RDBBlocksHi. All replacements for bad blocks should be between rdb_HighRDSKBlock+1 and rdb_RDBBlocksHi (inclusive).
- rdb_Reserved4
- Set to zeros.
These fields are of the form available from a SCSI Identify command. Their purpose is to help the user identify the disk during setup. Entries exist for both controller and disk for non-embedded SCSI disks.
- rdb_DiskVendor
- Vendor name of the disk.
- rdb_DiskProduct
- Product name of the disk.
- rdb_DiskRevision
- Revision code of the disk.
- rdb_ControllerVendor
- Vendor name of the disk controller.
- rdb_ControllerProduct
- Product name of the disk controller.
- rdb_ControllerRevision
- Revision code of the disk controller.
- rdb_Reserved5[10]
- Set to zeros.
BadBlockBlock
This is the current specification for the BadBlockBlock. The end of data occurs when bbb_Next is NULL ($FFFFFFFF), and the summed data is exhausted.
- bbb_ID
- Set to "BADB".
- bbb_SummedLongs
- Size of this checksummed structure.
- Note that this is not 64 like most of the other structures. This is the number of valid longs in this image, and can be from 6 to rdb_BlockBytes/4. The latter is the best size for all blocks other than the last one.
- bbb_ChkSum
- Block checksum (longword sum to zero).
- bbb_HostID
- SCSI Target ID of host.
- This describes the initiator ID for the creator of these blocks. (see rdb_HostID discussion)
- bbb_Next
- Block number of the next BadBlockBlock.
- bbb_Reserved
- Set to zeros.
- bbb_BlockPairs[61]
- Pairs of block remapping information.
- The data starts here and continues as long as indicated by bbb_SummedLongs-6: e.g. if bbb_SummedLongs is 128 (512 bytes), 61 pairs are described here.
PartitionBlock
This is the current specification for the PartitionBlock. Note that while reading these blocks you may encounter partitions that are not to be mounted because the pb_HostID does not match, or because the pb_DriveName is in use and no fallback strategy exists, or because PBFF_NOMOUNT is set, or because the proper file system cannot be found. Some partitions may be mounted but not be bootable because PBFF_BOOTABLE is not set.
- pb_ID
- Set to "PART".
- pb_SummedLongs
- Set to 64.
- pb_ChkSum
- Block checksum (longword sum to zero).
- pb_HostID
- SCSI Target ID of host.
- This describes the initiator ID for the owner of this partition. (see rdb_HostID discussion)
- pb_Next
- Block number of the next PartitionBlock.
- pb_Flags
- See below for defines:
- PBF._BOOTABLE
- This partition is intended to be bootable (e.g. expected directories and files exist).
- PBF._NOMOUNT
- This partition description is to reserve space on the disk without mounting it. It may be manually mounted later.
- pb_Reserved1[2]
- Set to zeros.
- pb_DevFlags
- Preferred flags for OpenDevice().
- pb_DriveName
- Preferred DOS device name: BSTR form This name is not to be used if it is already in use.
Note that pb_Reserved2 will always be at least 4 longwords so that the RAM image of this record may be converted to the parameter packet to the expansion.library function MakeDosNode().
- pb_Reserved2[15]
- Filler to make 32 longwords so far.
The specification of the location of the partition is one of the components of the environment, below. If possible, describe the partition in a manner that tells the DOS about the physical layout of the partition: specifically, where the cylinder boundaries are. This allows the file system's smart block allocation strategy to work.
- pb_Environment[17]
- Environment vector for this partition containing:
- de_TableSize
- Size of environment vector.
- de_SizeBlock
- Set to 128 (for 512 bytes/logical block).
- de_SecOrg
- Set to 0.
- de_Surfaces
- Number of heads (see layout discussion).
- de_SectorPerBlock
- Set to 1.
- de_BlocksPerTrack
- Blocks per track (see layout discussion).
- de_Reserved
- DOS reserved blocks at start of partition.
- Must be > 1; 2 blocks are recommended.
- de_PreAlloc
- DOS reserved blocks at end of partition.
- Valid only for file system type "DOS\1" (the fast file system). Zero otherwise.
- de_Interleave
- DOS interleave.
- Valid only for file system type "DOS\0" (the old file system). Zero otherwise.
- de_LowCyl
- Starting cylinder.
- de_HighCyl
- Max cylinder.
- de_NumBuffers
- Initial number of DOS buffers.
- de_BufMemType
- Type of mem to allocate for buffers.
- The second argument to AllocMem().
- de_MaxTransfer
- Max number of bytes to transfer at a time. Drivers should be written to handle requests of any length.
- de_Mask
- Address mask to block out certain memory.
- Normally $00FFFFFF for DMA devices.
- de_BootPri
- Boot priority for autoboot.
- Suggested value: zero. Keep less than five, so it won't override a boot floppy.
- de_DosType
- ASCII string showing fil esystem type;
- "DOS\0" ($444F5300) is old file system
- "DOS\1" ($444F5301) is fast file system
- "UNI(anything)" is a Unix partition
- pb_EReserved[15]
- Reserved for future environment vector.
FileSysHeaderBlock
The current specification for the FileSysHeaderBlock follows.
- fhb_ID
- Set to "FSHD".
- fhb_SummedLongs
- Set to 64.
- fhb_ChkSum
- Block checksum (long word sum to zero).
- fhb_HostID
- SCSI Target ID of host.
- This describes the initiator ID for the creator of this block. (see rdb_HostID discussion)
- fhb_Next
- Block number of next FileSysHeaderBlock.
- fhb_Flags
- See below for defines.
- fhb_Reserved1[2]
- Set to zero.
The following information is used to construct a FileSysEntry node in the FileSystem.resource.
- fhb_DosType
- File system description.
- This is matched with a partition environment's de_DosType entry.
- fhb_Version
- Release version of this load image.
- Usually, upper 16 bits hold version number, lower 16 bits hold revision number.
- fhb_PatchFlags
- Patch flags.
- These are bits set for those of the following that need to be substituted into a standard device node for this file system, lsb first: e.g. 0x180 to substitute SegList & GlobalVec
- fhb_Type
- Device node type: zero.
- fhb_Task
- Standard DOS "task" field: zero.
- fhb_Lock
- Not used for devices: zero.
- fhb_Handler
- File name to loadseg: zero placeholder.
- fhb_StackSize
- Stack size to use when starting task.
- fhb_Priority
- Task priority when starting task.
- fhb_Startup
- Startup message: zero placeholder.
- fhb_SegListBlocks
- First of linked list of LoadSegBlocks:
- Note that if the fhb_PatchFlags bit for this entry is set (bit 7), the blocks pointed to by this entry must be LoadSeg'd and the resulting BPTR put in the FileSysEntry node.
- fhb_GlobalVec
- BCPL global vector when starting task Zero or -1.
- fhb_Reserved2[23]
- (Those reserved by fhb_PatchFlags)
- fhb_Reserved3[21]
- Set to zero.
LoadSegBlock
This is the current specification of the LoadSegBlock. The end of data occurs when lsb_Next is NULL ($FFFF FFFF), and the summed data is exhausted.
- lsb_ID
- Set to "LSEG".
- lsb_SummedLongs
- Size of this checksummed structure.
- Note that this is not 64 like most of the other structures. This is the number of valid longs in this image, like bbb_SummedLongs.
- lsb_ChkSum
- Block checksum (longword sum to zero).
- lsb_HostID
- SCSI Target ID of host.
- This describes the initiator ID for the creator of these blocks. (see rdb_HostID discussion)
- lsb_Next
- Block number of the next LoadSegBlock.
- lsb_LoadData
- Data for "loadseg".
- The data starts here and continues as long as indicated by lsb_SummedLongs - 5: e.g. if lsb_SummedLongs is 128 (ie. for 512 byte blocks), 123 longs of data are valid here.
filesysres.h
The FileSysResource is created by the first code that needs to use it. It is added to the resource list for others to use. (Checking and creation should be performed while Forbid() is in effect). The resource is created by the system early on in the initialization sequence.
FileSysResource
- fsr_Node
- On resource list with the name "FileSystem.resource".
- fsr_Creator
- Name of creator of this resource.
- fsr_FileSysEntries
- List of FileSysEntry structs.
FileSysEntry
- fse_Node
- On fsr_FileSysEntries list; ln_Name is of creator of this entry.
- fse_DosType
- DosType of this file system.
- fse_Version
- Release version of this file system.
- Usually, upper 16 bits hold version number, lower 16 bits hold revision number.
- fse_PatchFlags
- Bits set for those of the following that need to be substituted into a standard device node for this file system: e.g. $180 for substitute SegList & GlobalVec.
- fse_Type
- Device node type: zero.
- fse_Task
- Standard DOS "task" field.
- fse_Lock
- Not used for devices: zero.
- fse_Handler
- File name to loadseg (if SegList is NULL).
- fse_StackSize
- Stack size to use when starting task.
- fse_Priority
- Task priority when starting task.
- fse_Startup
- Startup message: FileSysStartupMsg for disks.
- fse_SegList
- Segment of code to run to start new task.
- fse_GlobalVec
- BCPL global vector when starting task.
No more entries need exist than those implied by fse_PatchFlags, so entries do not have a fixed size.
For additional information on initializing and booting a Rigid Disk Block file system device, see the SCSI Device. Writers of drivers for expansion devices that perform their own DMA (direct memory access) should consult the Exec chapters and Autodocs for information on processor cache control functions including CachePreDMA() and CachePostDMA().
See the following include files for additional notes and related structures: <libraries/configvers.h>, <libraries/configregs.h>, <devices/hardblocks.h>, <resources/filesysres.h> and <libraries/filehandler.h>.
Function Reference
The following are brief descriptions of the expansion library functions that are useful for expansion device drivers and related applications. See the SDK for the complete descriptions of all the expansion library functions.
| Function | Description |
|---|---|
| FindConfigDev() | Returns a pointer to the ConfigDev structure of a given expansion device. |
| MakeDosNode() | Creates the DOS device node for disk and similar expansion devices. |
| AddDosNode() | Adds a DOS device node to the system. |
| AddBootNode() | Adds an autobooting DOS device node to the system. |
| GetCurrentBinding() | Returns a pointer to the CurrentBinding structure of a given device. |
| SetCurrentBinding() | Set up for reading the CurrentBinding with GetCurrentBinding(). |
| ObtainCurrentBinding() | Protect the ConfigDev structure with a semaphore. |
| ReleaseCurrentBinding() | Release a semaphore on ConfigDev set up with ObtainCurrentBinding(). |
