LoadSeg

Load a file into memory whose contents represent structured data and/or program code suitable for execution as a Task or Program

The file 'name' should be a "load file" (structured data and/or executable program code) produced by the tools which Amiga software developers use to create programs, shared libraries and device drivers.

LoadSeg() allocates memory for the load file components of the CODE, DATA and BSS types (these are called "segments"), then proceeds to read and transfer this information from the load file into memory. These segments are then connected together as a segment list, or "seglist" for short, which forms a "load module" which may be later unloaded again through the UnLoadSeg() function. There can be any number of segments in a load module.

In the event of an error, any segments loaded so far are unloaded and a NULL result is returned.

In case 'name' is non-NULL and scatter loading was aborted due to a HUNK_BREAK, i.e. an overlayed binary was found, LoadSeg() checks whether the first hunk has at offset 8 the magic long word constant $ABCD (decimal: 43981). The binary shall reserve four long words following this magic identifier. The four longwords are then filled in as follows:

1. Overlay FileHandle. This is to be used for loading subsequent

2. Pointer to the overlay table, the contents of the HUNK_OVERLAY.

3. Pointer to the hunk table, which contains references to every

4. Global vector of the dos.library, for BCPL code, also required

While this function is generally documented to take only a single argument, and the AmigaDOS function prototypes only document the one-argument variant, it actually takes two additional arguments in registers D2 and D3 if the first argument in register D1 (name) is NULL. This calling convention of LoadSeg() is used for programs using overlay segments, and then loads an overlay segment according to the hunk table in register D2, from the FileHandle in register D3.

name

pointer to a null-terminated string, or NULL.

table

BPTR to a hunk table, only used for overlayed segments if the name parameter is NULL

fh

BPTR to a FileHandle from which the overlayed segment is loaded if the name parameter is NULL.

seglist

BCPL pointer to a segment list, or NULL for failure. Call IoErr() to find out why LoadSeg() has failed.

The LoadSeg() function performs "scatter loading", which means that the contents of a "load file" will never be loaded to predefined addresses in the memory space of the Amiga. Instead, memory will be dynamically allocated for each segment of the load file. The segments will be "scattered" across the memory space of the Amiga. LoadSeg() adjusts the contents of the load file by a process known as "relocation" so that memory references between the individual segments, such as code to data, etc. will work out.

A load file may contain overlay information which is managed by the LoadSeg() function and the overlay management code which is part of the load file itself. Overlays allow for programs to be written whose total size by far exceeds the available working memory of the Amiga. This is achieved by preplanning which parts of the program have to be in memory at all times, and which combination of its parts may have to be in memory only when there is need for it. The program can then decide at runtime which parts are required, unloading and reloading other parts as needed.

This is a complex feature of dos.library and the Amiga software development tools which enable it were used prominently in the early years of 1985-1988 until modern Amigas came to have more than just 512 KBytes of RAM installed. Details on how the overlay features work are described in the AmigaDOS manual's developer section.

UnLoadSeg(), InternalLoadSeg(), InternalUnLoadSeg(), CreateProc(), CreateNewProc(), NewLoadSeg().