amiga-bootcamp/04_linking_and_libraries/library_structure.md

[← Home](../README.md) · [Linking & Libraries](README.md)

# AmigaOS Library Structure — Architecture, Construction, Memory Layout

## Overview

Every AmigaOS library, device, and resource is a **struct Library** preceded by a negative-offset JMP table. This document covers the complete memory layout, how `MakeLibrary()` constructs a library from scratch, the function vector table encoding, checksum verification, and how to create your own shared libraries.

---

## Memory Layout

```
Low addresses                                              High addresses
──────────────────────────────────────────────────────────────────────────

┌──────────────────────────────────┬──────────────────────────────────┐
│       JMP Table (negative)       │      Library Data (positive)     │
│                                  │                                  │
│  base - N:  JMP func_N          │  base + $00: struct Library      │
│  ...                             │  base + $22: lib_OpenCnt         │
│  base - 36: JMP func_6          │  base + $24: [private data]      │
│  base - 30: JMP func_5 (1st user)│  base + $XX: [more private]     │
│  base - 24: JMP Reserved        │                                  │
│  base - 18: JMP Expunge         │                                  │
│  base - 12: JMP Close           │                                  │
│  base - 6:  JMP Open            │                                  │
└──────────────────────────────────┴──────────────────────────────────┘
                                   ↑
                            Library Base Pointer
                         (returned by OpenLibrary)
```

### Memory Allocation

The library occupies a **single contiguous allocation**:

```c
/* Total allocation = JMP table + Library header + private data */
ULONG total = lib_NegSize + lib_PosSize;

/* AllocMem returns the start of the block */
APTR block = AllocMem(total, MEMF_PUBLIC | MEMF_CLEAR);

/* Library base pointer = block + lib_NegSize */
struct Library *lib = (struct Library *)((UBYTE *)block + lib_NegSize);
```

---

## The Library Node

```c
/* exec/libraries.h */
struct Library {
    struct Node  lib_Node;       /* +$00: linked list node (14 bytes) */
    UBYTE        lib_Flags;      /* +$0E: LIBF_ flags */
    UBYTE        lib_pad;        /* +$0F: alignment padding */
    UWORD        lib_NegSize;    /* +$10: bytes of JMP table */
    UWORD        lib_PosSize;    /* +$12: bytes of Library struct + private */
    UWORD        lib_Version;    /* +$14: major version */
    UWORD        lib_Revision;   /* +$16: minor revision */
    APTR         lib_IdString;   /* +$18: "mylib.library 1.0 (1.1.95)\r\n" */
    ULONG        lib_Sum;        /* +$1C: checksum of JMP table */
    UWORD        lib_OpenCnt;    /* +$20: current open count */
};
/* sizeof(struct Library) = 34 bytes ($22) */
```

### The Node Header

```c
/* exec/nodes.h */
struct Node {
    struct Node *ln_Succ;    /* +$00: next node in list */
    struct Node *ln_Pred;    /* +$04: previous node */
    UBYTE        ln_Type;    /* +$08: NT_LIBRARY, NT_DEVICE, NT_RESOURCE */
    BYTE         ln_Pri;     /* +$09: priority (for Enqueue) */
    char        *ln_Name;    /* +$0A: "dos.library" */
};
```

| ln_Type Value | Hex | Type |
|---|---|---|
| `NT_LIBRARY` | $09 | Standard shared library |
| `NT_DEVICE` | $03 | I/O device (trackdisk.device, etc.) |
| `NT_RESOURCE` | $08 | Hardware resource (cia.resource, etc.) |

---

## JMP Table Encoding

Each function vector is a 6-byte absolute JMP instruction:

```
Bytes: 4E F9 AA AA AA AA
        └──┘ └──────────┘
        JMP   32-bit absolute target address
        .L
```

### Why 6 Bytes?

The 68000 `JMP (xxx).L` instruction is exactly 6 bytes:
- 2 bytes: opcode `$4EF9`
- 4 bytes: 32-bit absolute address

This is the most compact way to do an indirect jump to an arbitrary address. The fixed 6-byte slot size allows the LVO to be calculated as a simple multiplication: `LVO = -(function_index × 6)`.

### Calling Through the JMP Table

```asm
; User code:
    MOVEA.L _DOSBase, A6       ; load library base into A6
    JSR     -48(A6)            ; jump to JMP table slot at base-48

; CPU executes:
;   1. Push return address onto stack
;   2. Compute effective address: A6 + (-48) = base - 48
;   3. Read 6 bytes at that address: 4EF9 AAAAAAAA
;   4. Jump to AAAAAAAA (the actual function body)
;   5. Function executes and RTS returns to caller
```

The double-jump (JSR→JMP→function→RTS) costs approximately 12 extra cycles on a 68000 — negligible compared to function execution time.

### Standard Functions (Mandatory for All Libraries)

| LVO | Index | Function | Purpose |
|---|---|---|---|
| −6 | 1 | `Open()` | Called by `OpenLibrary()` — increment refcount, return base |
| −12 | 2 | `Close()` | Called by `CloseLibrary()` — decrement refcount |
| −18 | 3 | `Expunge()` | Free resources when refcount reaches 0 |
| −24 | 4 | `Reserved()` | Must return 0 — reserved for future use |
| −30 | 5 | (first public function) | Library-specific — defined by `.fd` file |

---

## MakeLibrary() — Building a Library

```c
struct Library *MakeLibrary(
    APTR   funcArray,     /* A0: function pointer array */
    APTR   structInit,    /* A1: struct initializer table (or NULL) */
    APTR   initFunc,      /* A2: init function (or NULL) */
    ULONG  dataSize,      /* D0: sizeof(MyLibBase) */
    BPTR   segList         /* D1: segment list (for UnLoadSeg on expunge) */
);
```

### Function Array Formats

`funcArray` can be in two formats:

**Format 1: Absolute Pointers** (most common for C libraries)

```c
/* NULL-terminated array of function pointers */
APTR myFuncArray[] = {
    (APTR)MyOpen,        /* LVO -6 */
    (APTR)MyClose,       /* LVO -12 */
    (APTR)MyExpunge,     /* LVO -18 */
    (APTR)NULL,          /* LVO -24: Reserved */
    (APTR)MyFunc1,       /* LVO -30 */
    (APTR)MyFunc2,       /* LVO -36 */
    (APTR)-1             /* terminator */
};
```

**Format 2: Relative Offsets** (used by ROM modules)

```c
/* First entry = -1 signals relative mode */
/* Following entries are WORD offsets from funcArray base */
WORD myFuncArray[] = {
    -1,                   /* flag: relative mode */
    MyOpen - funcBase,    /* WORD offset to Open */
    MyClose - funcBase,   /* WORD offset to Close */
    MyExpunge - funcBase, /* WORD offset to Expunge */
    0,                    /* Reserved = NULL (offset 0 maps to a NOP) */
    MyFunc1 - funcBase,
    MyFunc2 - funcBase,
    -1                    /* terminator */
};
```

### MakeLibrary Internals

```c
/* What MakeLibrary does internally: */

/* 1. Count functions by scanning funcArray to the terminator */
ULONG numFuncs = CountFunctions(funcArray);
ULONG negSize = numFuncs * 6;  /* 6 bytes per JMP slot */

/* 2. Allocate combined block */
ULONG posSize = MAX(dataSize, sizeof(struct Library));
APTR block = AllocMem(negSize + posSize, MEMF_PUBLIC | MEMF_CLEAR);
struct Library *lib = (struct Library *)((UBYTE *)block + negSize);

/* 3. Fill JMP table using MakeFunctions() */
MakeFunctions(lib, funcArray, NULL);
/* For each function pointer, writes:
   *(UWORD *)(slot) = 0x4EF9;         // JMP.L opcode
   *(ULONG *)(slot + 2) = funcAddr;   // target address */

/* 4. Initialize struct Library fields */
lib->lib_NegSize = negSize;
lib->lib_PosSize = posSize;

/* 5. Apply structInit table (if provided) */
if (structInit)
    InitStruct(structInit, lib, 0);

/* 6. Call init function (if provided) */
if (initFunc)
    lib = ((struct Library *(*)(struct Library *, BPTR, struct ExecBase *))
           initFunc)(lib, segList, SysBase);

/* 7. Compute and store checksum */
SumLibrary(lib);

return lib;
```

---

## Creating a Shared Library — Complete Example

### Library Source (my.library)

```c
#include <exec/types.h>
#include <exec/libraries.h>
#include <exec/resident.h>
#include <proto/exec.h>

/* Private library base — extends struct Library */
struct MyLibBase {
    struct Library lib;          /* MUST be first */
    ULONG          myPrivate;   /* library-specific data */
    BPTR           segList;     /* for Expunge to UnLoadSeg */
};

/* Forward declarations */
struct Library * __saveds MyOpen(void);
BPTR __saveds MyClose(void);
BPTR __saveds MyExpunge(void);
ULONG MyReserved(void);
LONG __saveds MyAdd(LONG a __asm("d0"), LONG b __asm("d1"));

/* Function table */
static APTR FuncTable[] = {
    (APTR)MyOpen,
    (APTR)MyClose,
    (APTR)MyExpunge,
    (APTR)MyReserved,
    (APTR)MyAdd,           /* LVO -30: first user function */
    (APTR)-1
};

/* Struct init table */
static struct MyInitData {
    /* ... InitStruct data to set lib_Node.ln_Type, ln_Name, etc. */
} InitData;

/* Init function — called once when library first loads */
struct Library * __saveds LibInit(
    struct MyLibBase *base __asm("d0"),
    BPTR segList __asm("a0"),
    struct ExecBase *sysBase __asm("a6"))
{
    base->segList = segList;
    base->myPrivate = 0;
    return (struct Library *)base;
}

/* RomTag — how exec finds us */
static struct Resident RomTag = {
    RTC_MATCHWORD,              /* $4AFC */
    &RomTag,                     /* pointer to self */
    &RomTag + 1,                /* end skip */
    RTF_AUTOINIT,               /* auto-init flag */
    1,                           /* version */
    NT_LIBRARY,                 /* type */
    0,                           /* priority */
    "my.library",               /* name */
    "my.library 1.0 (1.1.95)\r\n",
    &AutoInitTable              /* init — points to auto-init array */
};

/* Auto-init table (for RTF_AUTOINIT) */
static ULONG AutoInitTable[] = {
    sizeof(struct MyLibBase),   /* data size */
    (ULONG)FuncTable,          /* function array */
    (ULONG)&InitData,          /* struct init data */
    (ULONG)LibInit             /* init function */
};

/* LVO -6: Open */
struct Library * __saveds MyOpen(void)
{
    struct MyLibBase *base = (struct MyLibBase *)
        REG_A6;  /* library base passed in A6 */
    base->lib.lib_OpenCnt++;
    base->lib.lib_Flags &= ~LIBF_DELEXP;
    return (struct Library *)base;
}

/* LVO -12: Close */
BPTR __saveds MyClose(void)
{
    struct MyLibBase *base = (struct MyLibBase *)REG_A6;
    base->lib.lib_OpenCnt--;
    if (base->lib.lib_OpenCnt == 0 &&
        (base->lib.lib_Flags & LIBF_DELEXP))
    {
        return MyExpunge();
    }
    return 0;
}

/* LVO -18: Expunge */
BPTR __saveds MyExpunge(void)
{
    struct MyLibBase *base = (struct MyLibBase *)REG_A6;
    if (base->lib.lib_OpenCnt > 0)
    {
        base->lib.lib_Flags |= LIBF_DELEXP;
        return 0;  /* Can't expunge yet — still in use */
    }

    BPTR seg = base->segList;
    Remove(&base->lib.lib_Node);   /* Remove from LibList */
    FreeMem((UBYTE *)base - base->lib.lib_NegSize,
            base->lib.lib_NegSize + base->lib.lib_PosSize);
    return seg;  /* Return segment list for UnLoadSeg */
}

/* LVO -24: Reserved */
ULONG MyReserved(void) { return 0; }

/* LVO -30: Your first function */
LONG __saveds MyAdd(LONG a __asm("d0"), LONG b __asm("d1"))
{
    return a + b;
}
```

### Corresponding .fd File

```
##base _MyBase
##bias 30
##public
Add(a,b)(D0,D1)
##end
```

---

## Library Flags

```c
/* lib_Flags bits: */
#define LIBF_SUMMING   (1<<0)   /* Currently computing checksum */
#define LIBF_CHANGED   (1<<1)   /* JMP table was patched (SetFunction) */
#define LIBF_SUMUSED   (1<<2)   /* Checksum is valid and in use */
#define LIBF_DELEXP    (1<<3)   /* Delayed expunge — expunge when refcount=0 */
```

| Flag | Set By | Checked By |
|---|---|---|
| `LIBF_SUMMING` | `SumLibrary()` | Internal — prevents recursive sum |
| `LIBF_CHANGED` | `SetFunction()` | `ShowConfig`, virus scanners — detect patches |
| `LIBF_SUMUSED` | `SumLibrary()` | `exec` — decides if checksum valid |
| `LIBF_DELEXP` | Memory-low handler | `Close()` — triggers deferred expunge |

---

## Checksum Verification

```c
/* SumLibrary() computes checksum over the JMP table: */
void SumLibrary(struct Library *lib)
{
    lib->lib_Flags |= LIBF_SUMMING;
    ULONG sum = 0;
    UWORD *p = (UWORD *)((UBYTE *)lib - lib->lib_NegSize);
    ULONG count = lib->lib_NegSize / 2;  /* in words */
    while (count--)
        sum += *p++;
    lib->lib_Sum = sum;
    lib->lib_Flags &= ~LIBF_SUMMING;
    lib->lib_Flags |= LIBF_SUMUSED;
}

/* To verify: recompute and compare to lib_Sum */
/* If mismatch: Alert(AN_LibChkSum) — Guru Meditation */
```

> **Anti-tamper**: exec periodically validates library checksums. If `SetFunction()` patches a library, it sets `LIBF_CHANGED` so exec skips the checksum check. Direct JMP table writes (bypassing `SetFunction`) will trigger a checksum Guru on the next validation pass.

---

## Library Lifecycle

```mermaid
stateDiagram-v2
    [*] --> OnDisk : LIBS:my.library file
    OnDisk --> Loading : OpenLibrary("my.library", 1)
    Loading --> Initialized : LoadSeg + MakeLibrary + LibInit
    Initialized --> Added : AddLibrary → SysBase→LibList
    Added --> Open : OpenLibrary → Open() LVO → lib_OpenCnt++
    Open --> Open : More OpenLibrary calls
    Open --> Closing : CloseLibrary → Close() LVO → lib_OpenCnt--
    Closing --> Added : lib_OpenCnt > 0
    Closing --> Expunging : lib_OpenCnt == 0
    Expunging --> [*] : Expunge() → FreeMem + UnLoadSeg
    Expunging --> Added : LIBF_DELEXP (deferred — still has openers)
```

---

## References

- NDK39: `exec/libraries.h`, `exec/nodes.h`, `exec/resident.h`
- ADCD 2.1 Autodocs: `OpenLibrary`, `MakeLibrary`, `MakeFunctions`, `AddLibrary`, `SetFunction`, `SumLibrary`
- *Amiga ROM Kernel Reference Manual: Libraries* — library architecture chapter
- See also: [SetFunction](setfunction.md) — runtime patching
- See also: [LVO Table](lvo_table.md) — complete offset tables
- See also: [Shared Libraries Runtime](shared_libraries_runtime.md) — OpenLibrary internals