mirror of
https://github.com/alfishe/amiga-bootcamp.git
synced 2026-06-13 00:26:28 +00:00
docs(amiga): complete AmigaOS 3.1/3.2 developer reference — 172 files across 17 sections
Comprehensive technical documentation covering: - Hardware: OCS/ECS/AGA custom chip registers, Copper & Blitter deep dives - Boot sequence: cold boot through startup-sequence - Binary format: HUNK executable spec, relocation, debug info - Linking & ABI: .fd files, LVO tables, register calling conventions - Exec kernel: tasks, interrupts, memory, signals, semaphores - AmigaDOS: file I/O, FFS/OFS layout, CLI/Shell scripting - Graphics: planar bitmaps, Copper programming, HAM/EHB modes - Intuition: screens, windows, IDCMP, BOOPSI - Devices: trackdisk, SCSI, serial, timer, audio, keyboard - Libraries: utility, expansion, IFFParse, locale, ARexx - Networking: bsdsocket API, SANA-II, TCP/IP stack comparison - Toolchain: GCC, vasm/vlink, SAS/C, NDK, debugging - Reverse engineering: IDA/Ghidra setup, compiler fingerprints, case studies - CPU & MMU: 68040/060 emulation libs, PMMU, cache management - Driver development: SANA-II, Picasso96/RTG, AHI audio All files include breadcrumb navigation. No local paths or proprietary content.
This commit is contained in:
Ilia Sharin
parent
f07a368bf1
commit
21751c0025
172 changed files with 19701 additions and 0 deletions
19
11_libraries/README.md
Normal file
19
11_libraries/README.md
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
[← Home](../README.md)
|
||||
|
||||
# Common Libraries — Overview
|
||||
|
||||
## Section Index
|
||||
|
||||
| File | Description |
|
||||
|---|---|
|
||||
| [utility.md](utility.md) | utility.library — TagItem, hooks, date |
|
||||
| [expansion.md](expansion.md) | expansion.library — Zorro/AutoConfig |
|
||||
| [icon.md](icon.md) | icon.library — Workbench icons (.info) |
|
||||
| [workbench.md](workbench.md) | workbench.library — Workbench integration |
|
||||
| [iffparse.md](iffparse.md) | iffparse.library — IFF file parsing |
|
||||
| [locale.md](locale.md) | locale.library — internationalisation |
|
||||
| [keymap.md](keymap.md) | keymap.library — keyboard mapping |
|
||||
| [rexxsyslib.md](rexxsyslib.md) | rexxsyslib.library — ARexx interface |
|
||||
| [mathffp.md](mathffp.md) | mathffp/mathieeesingbas — floating point |
|
||||
| [layers.md](layers.md) | layers.library — window clipping layers |
|
||||
| [diskfont.md](diskfont.md) | diskfont.library — disk-based fonts |
|
||||
57
11_libraries/diskfont.md
Normal file
57
11_libraries/diskfont.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# diskfont.library — Disk-Based Fonts
|
||||
|
||||
## Overview
|
||||
|
||||
`diskfont.library` loads bitmap fonts from disk (the `FONTS:` assign). ROM fonts (topaz 8, topaz 9) are always available; all others require this library.
|
||||
|
||||
---
|
||||
|
||||
## Loading a Disk Font
|
||||
|
||||
```c
|
||||
struct Library *DiskfontBase = OpenLibrary("diskfont.library", 0);
|
||||
|
||||
struct TextAttr ta = {"helvetica.font", 24, 0, 0};
|
||||
struct TextFont *font = OpenDiskFont(&ta);
|
||||
if (font) {
|
||||
SetFont(rp, font);
|
||||
/* ... render ... */
|
||||
CloseFont(font);
|
||||
}
|
||||
|
||||
CloseLibrary(DiskfontBase);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Font Directory Structure
|
||||
|
||||
```
|
||||
FONTS:
|
||||
helvetica.font ← font descriptor file
|
||||
helvetica/
|
||||
24 ← bitmap data for size 24
|
||||
11 ← bitmap data for size 11
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Listing Available Fonts
|
||||
|
||||
```c
|
||||
struct List *fontList = NULL;
|
||||
LONG count = AvailFonts(buf, bufsize, AFF_DISK | AFF_MEMORY);
|
||||
struct AvailFontsHeader *afh = (struct AvailFontsHeader *)buf;
|
||||
struct AvailFonts *af = (struct AvailFonts *)&afh[1];
|
||||
for (int i = 0; i < afh->afh_NumEntries; i++) {
|
||||
Printf("%s %ld\n", af[i].af_Attr.ta_Name, af[i].af_Attr.ta_YSize);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `diskfont/diskfont.h`
|
||||
82
11_libraries/expansion.md
Normal file
82
11_libraries/expansion.md
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# expansion.library — Zorro Bus and AutoConfig
|
||||
|
||||
## Overview
|
||||
|
||||
`expansion.library` handles automatic configuration of Zorro II/III expansion boards. At boot, the OS scans the expansion bus and assigns base addresses to each board based on its AutoConfig ROM.
|
||||
|
||||
---
|
||||
|
||||
## AutoConfig Sequence
|
||||
|
||||
1. Board asserts `CFGIN` to request configuration
|
||||
2. CPU reads 256-byte config area at `$E80000`
|
||||
3. Board reports: manufacturer ID, product ID, board size, flags
|
||||
4. OS assigns a base address via `WriteExpansionByte`
|
||||
5. Board relocates to assigned address
|
||||
6. Next board in chain is configured
|
||||
|
||||
---
|
||||
|
||||
## struct ConfigDev
|
||||
|
||||
```c
|
||||
/* libraries/configvars.h — NDK39 */
|
||||
struct ConfigDev {
|
||||
struct Node cd_Node;
|
||||
UBYTE cd_Flags; /* CDF_* flags */
|
||||
UBYTE cd_Pad;
|
||||
struct ExpansionRom cd_Rom; /* AutoConfig ROM data */
|
||||
APTR cd_BoardAddr; /* assigned base address */
|
||||
ULONG cd_BoardSize; /* board size in bytes */
|
||||
UWORD cd_SlotAddr; /* slot address */
|
||||
UWORD cd_SlotSize;
|
||||
APTR cd_Driver; /* driver bound to this board */
|
||||
struct ConfigDev *cd_NextCD; /* next in chain */
|
||||
/* ... */
|
||||
};
|
||||
|
||||
struct ExpansionRom {
|
||||
UBYTE er_Type; /* board type + size code */
|
||||
UBYTE er_Product; /* product number */
|
||||
UBYTE er_Flags;
|
||||
UBYTE er_Reserved03;
|
||||
UWORD er_Manufacturer; /* manufacturer ID */
|
||||
ULONG er_SerialNumber;
|
||||
UWORD er_InitDiagVec; /* boot ROM offset */
|
||||
/* ... */
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Finding Expansion Boards
|
||||
|
||||
```c
|
||||
struct Library *ExpansionBase = OpenLibrary("expansion.library", 0);
|
||||
struct ConfigDev *cd = NULL;
|
||||
|
||||
while ((cd = FindConfigDev(cd, 2167, 11))) {
|
||||
/* manufacturer=2167 (Individual Computers), product=11 (ACA500plus) */
|
||||
Printf("Board at $%08lx, size %lu\n", cd->cd_BoardAddr, cd->cd_BoardSize);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Manufacturer IDs
|
||||
|
||||
| ID | Manufacturer |
|
||||
|---|---|
|
||||
| 514 | Commodore |
|
||||
| 2017 | GVP |
|
||||
| 2167 | Individual Computers |
|
||||
| 8512 | Phase5 |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `libraries/configvars.h`, `libraries/expansion.h`
|
||||
- ADCD 2.1: expansion.library autodocs
|
||||
66
11_libraries/icon.md
Normal file
66
11_libraries/icon.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# icon.library — Workbench Icons (.info Files)
|
||||
|
||||
## Overview
|
||||
|
||||
Every Workbench-visible file has a companion `.info` file containing its icon imagery, tooltypes, and default tool. `icon.library` provides reading/writing these structures.
|
||||
|
||||
---
|
||||
|
||||
## struct DiskObject
|
||||
|
||||
```c
|
||||
/* workbench/workbench.h — NDK39 */
|
||||
struct DiskObject {
|
||||
UWORD do_Magic; /* $E310 = WB_DISKMAGIC */
|
||||
UWORD do_Version; /* WB_DISKVERSION */
|
||||
struct Gadget do_Gadget; /* the icon gadget */
|
||||
UBYTE do_Type; /* WBDISK, WBTOOL, WBPROJECT, etc. */
|
||||
char *do_DefaultTool; /* default tool path */
|
||||
char **do_ToolTypes; /* NULL-terminated string array */
|
||||
LONG do_CurrentX; /* icon X position */
|
||||
LONG do_CurrentY; /* icon Y position */
|
||||
BPTR do_DrawerData; /* drawer window position (BPTR) */
|
||||
char *do_ToolWindow; /* tool window spec */
|
||||
LONG do_StackSize; /* stack size for tool */
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Icon Types
|
||||
|
||||
| Constant | Value | Description |
|
||||
|---|---|---|
|
||||
| `WBDISK` | 1 | Disk/volume icon |
|
||||
| `WBDRAWER` | 2 | Drawer (directory) |
|
||||
| `WBTOOL` | 3 | Executable tool |
|
||||
| `WBPROJECT` | 4 | Project (document) |
|
||||
| `WBGARBAGE` | 5 | Trashcan |
|
||||
| `WBDEVICE` | 6 | Device |
|
||||
| `WBKICK` | 7 | Kickstart disk |
|
||||
| `WBAPPICON` | 8 | AppIcon (OS 2.0+) |
|
||||
|
||||
---
|
||||
|
||||
## ToolTypes
|
||||
|
||||
ToolTypes are key=value strings stored in `do_ToolTypes`:
|
||||
|
||||
```c
|
||||
struct DiskObject *dobj = GetDiskObject("myapp");
|
||||
if (dobj) {
|
||||
char *val = FindToolType(dobj->do_ToolTypes, "PUBSCREEN");
|
||||
if (val) Printf("Screen: %s\n", val);
|
||||
if (MatchToolValue(FindToolType(dobj->do_ToolTypes, "FLAGS"), "DEBUG"))
|
||||
Printf("Debug mode\n");
|
||||
FreeDiskObject(dobj);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `workbench/workbench.h`, `workbench/icon.h`
|
||||
81
11_libraries/iffparse.md
Normal file
81
11_libraries/iffparse.md
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# iffparse.library — IFF File Parsing
|
||||
|
||||
## Overview
|
||||
|
||||
IFF (Interchange File Format) is EA/Commodore's universal container format. `iffparse.library` provides stream-oriented parsing/writing of IFF files. Common IFF types: ILBM (images), 8SVX (audio), ANIM (animation), FTXT (formatted text).
|
||||
|
||||
---
|
||||
|
||||
## IFF Structure
|
||||
|
||||
```
|
||||
FORM <size> <type>
|
||||
<chunk_id> <size> <data...>
|
||||
<chunk_id> <size> <data...>
|
||||
...
|
||||
```
|
||||
|
||||
All values are big-endian. Chunks are padded to even byte boundaries.
|
||||
|
||||
---
|
||||
|
||||
## Key Functions
|
||||
|
||||
```c
|
||||
struct Library *IFFParseBase = OpenLibrary("iffparse.library", 0);
|
||||
struct IFFHandle *iff = AllocIFF();
|
||||
|
||||
/* Open from file: */
|
||||
iff->iff_Stream = (ULONG)Open("image.iff", MODE_OLDFILE);
|
||||
InitIFFasDOS(iff);
|
||||
OpenIFF(iff, IFFF_READ);
|
||||
|
||||
/* Register chunks we want to stop at: */
|
||||
StopChunk(iff, ID_ILBM, ID_BMHD);
|
||||
StopChunk(iff, ID_ILBM, ID_BODY);
|
||||
StopChunk(iff, ID_ILBM, ID_CMAP);
|
||||
|
||||
/* Parse: */
|
||||
LONG error;
|
||||
while ((error = ParseIFF(iff, IFFPARSE_SCAN)) == 0) {
|
||||
struct ContextNode *cn = CurrentChunk(iff);
|
||||
switch (cn->cn_ID) {
|
||||
case ID_BMHD:
|
||||
ReadChunkBytes(iff, &bmhd, sizeof(bmhd));
|
||||
break;
|
||||
case ID_CMAP:
|
||||
ReadChunkBytes(iff, palette, cn->cn_Size);
|
||||
break;
|
||||
case ID_BODY:
|
||||
ReadChunkBytes(iff, bodydata, cn->cn_Size);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
CloseIFF(iff);
|
||||
Close((BPTR)iff->iff_Stream);
|
||||
FreeIFF(iff);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Chunk IDs
|
||||
|
||||
| FORM Type | Chunk | Description |
|
||||
|---|---|---|
|
||||
| `ILBM` | `BMHD` | Bitmap header (width, height, depth) |
|
||||
| `ILBM` | `CMAP` | Colour map (R,G,B triples) |
|
||||
| `ILBM` | `BODY` | Image body data |
|
||||
| `ILBM` | `CAMG` | Amiga display mode |
|
||||
| `8SVX` | `VHDR` | Voice header |
|
||||
| `8SVX` | `BODY` | Audio sample data |
|
||||
| `ANIM` | `ANHD` | Animation header |
|
||||
| `ANIM` | `DLTA` | Delta frame data |
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `libraries/iffparse.h`, `datatypes/pictureclass.h`
|
||||
46
11_libraries/keymap.md
Normal file
46
11_libraries/keymap.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# keymap.library — Keyboard Mapping
|
||||
|
||||
## Overview
|
||||
|
||||
`keymap.library` translates raw keycodes from `keyboard.device` into character codes using the active keymap. Each keymap defines the mapping from physical keys to characters, including dead keys and string sequences.
|
||||
|
||||
---
|
||||
|
||||
## Key Functions
|
||||
|
||||
```c
|
||||
/* Map a raw keycode + qualifiers to ASCII: */
|
||||
LONG actual = MapRawKey(&inputEvent, buffer, bufsize, NULL);
|
||||
/* Returns number of characters, -1 if buffer too small */
|
||||
|
||||
/* Map ANSI code back to raw key: */
|
||||
WORD MapANSI(STRPTR string, WORD count,
|
||||
STRPTR buffer, WORD length,
|
||||
struct KeyMap *keyMap);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## struct KeyMap
|
||||
|
||||
```c
|
||||
/* devices/keymap.h — NDK39 */
|
||||
struct KeyMap {
|
||||
UBYTE *km_LoKeyMapTypes; /* type array for keys 0x00–0x3F */
|
||||
ULONG *km_LoKeyMap; /* mapping array for keys 0x00–0x3F */
|
||||
UBYTE *km_LoCapsable; /* caps-lock bitmap */
|
||||
UBYTE *km_LoRepeatable; /* auto-repeat bitmap */
|
||||
UBYTE *km_HiKeyMapTypes; /* type array for keys 0x40–0x77 */
|
||||
ULONG *km_HiKeyMap;
|
||||
UBYTE *km_HiCapsable;
|
||||
UBYTE *km_HiRepeatable;
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `devices/keymap.h`, `libraries/keymap.h`
|
||||
50
11_libraries/layers.md
Normal file
50
11_libraries/layers.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# layers.library — Window Clipping Layers
|
||||
|
||||
## Overview
|
||||
|
||||
`layers.library` provides the clipping and damage-repair infrastructure that Intuition windows are built on. Each window's `RastPort` is backed by a `Layer` that manages overlapping regions.
|
||||
|
||||
---
|
||||
|
||||
## Layer Types
|
||||
|
||||
| Flag | Type | Description |
|
||||
|---|---|---|
|
||||
| `LAYERSIMPLE` | Simple Refresh | Application must redraw damaged areas |
|
||||
| `LAYERSMART` | Smart Refresh | System saves obscured regions |
|
||||
| `LAYERSUPER` | Super BitMap | Application provides full-size bitmap |
|
||||
| `LAYERBACKDROP` | Backdrop | Behind all other layers |
|
||||
|
||||
---
|
||||
|
||||
## Key Functions
|
||||
|
||||
```c
|
||||
struct Layer_Info *li = NewLayerInfo();
|
||||
|
||||
struct Layer *layer = CreateUpfrontLayer(li, bitmap,
|
||||
x1, y1, x2, y2, LAYERSMART, NULL);
|
||||
|
||||
/* Lock before drawing: */
|
||||
LockLayer(0, layer);
|
||||
/* ... draw into layer->rp ... */
|
||||
UnlockLayer(layer);
|
||||
|
||||
/* Move: */
|
||||
MoveLayer(0, layer, dx, dy);
|
||||
|
||||
/* Resize: */
|
||||
SizeLayer(0, layer, dw, dh);
|
||||
|
||||
/* Cleanup: */
|
||||
DeleteLayer(0, layer);
|
||||
DisposeLayerInfo(li);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `graphics/layers.h`, `graphics/clip.h`
|
||||
46
11_libraries/locale.md
Normal file
46
11_libraries/locale.md
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# locale.library — Internationalisation
|
||||
|
||||
## Overview
|
||||
|
||||
`locale.library` (OS 2.1+) provides language-aware string lookup, date/number formatting, and character classification for internationalised applications.
|
||||
|
||||
---
|
||||
|
||||
## Core Pattern
|
||||
|
||||
```c
|
||||
struct Library *LocaleBase = OpenLibrary("locale.library", 38);
|
||||
struct Catalog *cat = OpenCatalog(NULL, "myapp.catalog",
|
||||
OC_BuiltInLanguage, "english",
|
||||
TAG_DONE);
|
||||
|
||||
/* Get localised string: */
|
||||
STRPTR str = GetCatalogStr(cat, MSG_HELLO, "Hello"); /* fallback */
|
||||
|
||||
CloseCatalog(cat);
|
||||
CloseLibrary(LocaleBase);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Locale-Aware Formatting
|
||||
|
||||
```c
|
||||
struct Locale *loc = OpenLocale(NULL); /* user's default */
|
||||
|
||||
/* Format a date: */
|
||||
FormatDate(loc, "%A %e %B %Y", &datestamp, &hook);
|
||||
|
||||
/* Format a number: */
|
||||
/* Uses loc->loc_GroupSeparator, loc->loc_DecimalPoint */
|
||||
|
||||
CloseLocale(loc);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `libraries/locale.h`
|
||||
69
11_libraries/mathffp.md
Normal file
69
11_libraries/mathffp.md
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# Math Libraries — Floating Point
|
||||
|
||||
## Overview
|
||||
|
||||
AmigaOS provides multiple math libraries for floating-point operations. The 68000 has no FPU, so all math is done in software unless a 68881/68882/68040/68060 FPU is present.
|
||||
|
||||
---
|
||||
|
||||
## Library Stack
|
||||
|
||||
| Library | Format | Description |
|
||||
|---|---|---|
|
||||
| `mathffp.library` | FFP (Motorola Fast Floating Point) | Original Amiga format (32-bit) |
|
||||
| `mathieeesingbas.library` | IEEE 754 single (32-bit) | IEEE single precision |
|
||||
| `mathieeedoubbas.library` | IEEE 754 double (64-bit) | IEEE double precision |
|
||||
| `mathtrans.library` | FFP | Transcendental functions (sin, cos, sqrt) |
|
||||
| `mathieeesingtrans.library` | IEEE single | IEEE single transcendentals |
|
||||
| `mathieeedoubtrans.library` | IEEE double | IEEE double transcendentals |
|
||||
|
||||
---
|
||||
|
||||
## FFP Format
|
||||
|
||||
Motorola FFP is NOT IEEE 754:
|
||||
```
|
||||
Bits 31–8: 24-bit mantissa (normalised, implicit 1.xxx)
|
||||
Bits 7–1: 7-bit exponent (excess-64)
|
||||
Bit 0: sign (0=positive, 1=negative)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using IEEE Math
|
||||
|
||||
```c
|
||||
struct Library *MathIeeeSingBasBase =
|
||||
OpenLibrary("mathieeesingbas.library", 0);
|
||||
|
||||
float a = 3.14f;
|
||||
float b = 2.0f;
|
||||
float c = IEEESPMul(a, b); /* 6.28 */
|
||||
float d = IEEESPAdd(a, b); /* 5.14 */
|
||||
float e = IEEESPDiv(a, b); /* 1.57 */
|
||||
|
||||
CloseLibrary(MathIeeeSingBasBase);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 68881/68882 FPU
|
||||
|
||||
When an FPU is present, the math libraries are replaced with ROM patches that use native FPU instructions. The application code is identical — the library transparently switches to hardware.
|
||||
|
||||
```c
|
||||
if (SysBase->AttnFlags & AFF_68881) {
|
||||
/* 68881/68882 FPU present */
|
||||
}
|
||||
if (SysBase->AttnFlags & AFF_FPU40) {
|
||||
/* 68040 internal FPU */
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `libraries/mathffp.h`, `libraries/mathieeesp.h`
|
||||
60
11_libraries/rexxsyslib.md
Normal file
60
11_libraries/rexxsyslib.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# rexxsyslib.library — ARexx Interface
|
||||
|
||||
## Overview
|
||||
|
||||
ARexx is the Amiga's built-in macro/scripting language (based on REXX). `rexxsyslib.library` provides APIs for hosting ARexx ports, sending commands, and receiving results.
|
||||
|
||||
---
|
||||
|
||||
## Adding an ARexx Port
|
||||
|
||||
```c
|
||||
struct MsgPort *arexxPort = CreateMsgPort();
|
||||
arexxPort->mp_Node.ln_Name = "MYAPP";
|
||||
arexxPort->mp_Node.ln_Pri = 0;
|
||||
AddPort(arexxPort);
|
||||
|
||||
/* In event loop, check for ARexx messages: */
|
||||
struct RexxMsg *rmsg;
|
||||
while ((rmsg = (struct RexxMsg *)GetMsg(arexxPort))) {
|
||||
STRPTR cmd = ARG0(rmsg); /* the command string */
|
||||
/* Parse and execute command... */
|
||||
rmsg->rm_Result1 = 0; /* RC = 0 (success) */
|
||||
rmsg->rm_Result2 = 0;
|
||||
ReplyMsg((struct Message *)rmsg);
|
||||
}
|
||||
|
||||
RemPort(arexxPort);
|
||||
DeleteMsgPort(arexxPort);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sending ARexx Commands
|
||||
|
||||
```c
|
||||
struct MsgPort *replyPort = CreateMsgPort();
|
||||
struct RexxMsg *rmsg = CreateRexxMsg(replyPort, NULL, NULL);
|
||||
rmsg->rm_Args[0] = CreateArgstring("QUIT", 4);
|
||||
rmsg->rm_Action = RXCOMM;
|
||||
|
||||
struct MsgPort *target = FindPort("TARGETAPP");
|
||||
if (target) {
|
||||
PutMsg(target, &rmsg->rm_Node);
|
||||
WaitPort(replyPort);
|
||||
GetMsg(replyPort);
|
||||
/* rmsg->rm_Result1 = return code */
|
||||
}
|
||||
|
||||
DeleteArgstring(rmsg->rm_Args[0]);
|
||||
DeleteRexxMsg(rmsg);
|
||||
DeleteMsgPort(replyPort);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `rexx/storage.h`, `rexx/rxslib.h`
|
||||
86
11_libraries/utility.md
Normal file
86
11_libraries/utility.md
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# utility.library — TagItems, Hooks, Date Utilities
|
||||
|
||||
## Overview
|
||||
|
||||
`utility.library` (OS 2.0+) provides the universal tag-based parameter passing system, callback hooks, and date/time utilities used throughout AmigaOS.
|
||||
|
||||
---
|
||||
|
||||
## TagItem System
|
||||
|
||||
```c
|
||||
/* utility/tagitem.h — NDK39 */
|
||||
struct TagItem {
|
||||
ULONG ti_Tag; /* tag identifier */
|
||||
ULONG ti_Data; /* tag value */
|
||||
};
|
||||
|
||||
/* Special tag values: */
|
||||
#define TAG_DONE 0 /* end of tag list */
|
||||
#define TAG_END TAG_DONE
|
||||
#define TAG_IGNORE 1 /* skip this tag */
|
||||
#define TAG_MORE 2 /* ti_Data = pointer to another TagItem array */
|
||||
#define TAG_SKIP 3 /* skip next ti_Data tags */
|
||||
#define TAG_USER (1<<31) /* user-defined tags start here */
|
||||
```
|
||||
|
||||
### Tag Utility Functions
|
||||
|
||||
| Function | Description |
|
||||
|---|---|
|
||||
| `FindTagItem(tag, tagList)` | Find first matching tag |
|
||||
| `GetTagData(tag, default, tagList)` | Get tag value with default |
|
||||
| `NextTagItem(&tagListPtr)` | Iterate through tags |
|
||||
| `TagInArray(tag, array)` | Check if tag is in an array |
|
||||
| `FilterTagItems(tagList, filter, logic)` | Filter tag list |
|
||||
| `CloneTagItems(tagList)` | Allocate copy of tag list |
|
||||
| `FreeTagItems(tagList)` | Free cloned tag list |
|
||||
| `MapTags(tagList, mapList, flags)` | Remap tag IDs |
|
||||
|
||||
---
|
||||
|
||||
## Hook System
|
||||
|
||||
```c
|
||||
/* utility/hooks.h */
|
||||
struct Hook {
|
||||
struct MinNode h_MinNode;
|
||||
ULONG (*h_Entry)(void); /* assembler entry point */
|
||||
ULONG (*h_SubEntry)(void); /* C function pointer */
|
||||
APTR h_Data; /* user data */
|
||||
};
|
||||
```
|
||||
|
||||
Convention: `h_Entry` receives `A0=hook, A2=object, A1=message`.
|
||||
|
||||
```c
|
||||
/* Convenience macro for SAS/C and GCC: */
|
||||
ULONG myHookFunc(struct Hook *hook __asm("a0"),
|
||||
Object *obj __asm("a2"),
|
||||
APTR msg __asm("a1"))
|
||||
{
|
||||
/* ... */
|
||||
return 0;
|
||||
}
|
||||
|
||||
struct Hook myHook = { {NULL}, (HOOKFUNC)myHookFunc, NULL, myData };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Date Utilities
|
||||
|
||||
```c
|
||||
struct ClockData cd;
|
||||
Amiga2Date(seconds, &cd); /* seconds since 1.1.1978 → date */
|
||||
ULONG secs = Date2Amiga(&cd); /* date → seconds */
|
||||
ULONG secs = CheckDate(&cd); /* validate and convert */
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `utility/tagitem.h`, `utility/hooks.h`, `utility/date.h`
|
||||
74
11_libraries/workbench.md
Normal file
74
11_libraries/workbench.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
[← Home](../README.md) · [Libraries](README.md)
|
||||
|
||||
# workbench.library — Workbench Integration
|
||||
|
||||
## Overview
|
||||
|
||||
`workbench.library` provides APIs for interacting with the Workbench desktop: AppWindows, AppIcons, AppMenuItems, and startup message handling.
|
||||
|
||||
---
|
||||
|
||||
## WBStartup Message
|
||||
|
||||
When launched from Workbench, a program receives a `WBStartup` message instead of CLI arguments:
|
||||
|
||||
```c
|
||||
struct WBStartup {
|
||||
struct Message sm_Message;
|
||||
struct MsgPort *sm_Process; /* process that sent us */
|
||||
BPTR sm_Segment; /* our loaded segment */
|
||||
LONG sm_NumArgs; /* number of arguments */
|
||||
char *sm_ToolWindow; /* tool window spec */
|
||||
struct WBArg *sm_ArgList; /* argument array */
|
||||
};
|
||||
|
||||
struct WBArg {
|
||||
BPTR wa_Lock; /* directory lock */
|
||||
BYTE *wa_Name; /* filename */
|
||||
};
|
||||
```
|
||||
|
||||
### Handling WBStartup
|
||||
|
||||
```c
|
||||
struct WBStartup *wbmsg = NULL;
|
||||
if (!argc) { /* launched from Workbench */
|
||||
WaitPort(&((struct Process *)FindTask(NULL))->pr_MsgPort);
|
||||
wbmsg = (struct WBStartup *)GetMsg(
|
||||
&((struct Process *)FindTask(NULL))->pr_MsgPort);
|
||||
/* Process wbmsg->sm_ArgList for file arguments */
|
||||
}
|
||||
/* ... do work ... */
|
||||
if (wbmsg) {
|
||||
Forbid();
|
||||
ReplyMsg((struct Message *)wbmsg);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AppWindow / AppIcon / AppMenuItem
|
||||
|
||||
```c
|
||||
/* Register a window to receive file drops: */
|
||||
struct AppWindow *appwin = AddAppWindow(1, 0, win, port, NULL);
|
||||
/* When user drags files to the window, receive AppMessage on port */
|
||||
|
||||
struct AppMessage {
|
||||
struct Message am_Message;
|
||||
UWORD am_Type; /* AMTYPE_APPWINDOW, etc. */
|
||||
ULONG am_UserData;
|
||||
ULONG am_ID;
|
||||
LONG am_NumArgs; /* number of files dropped */
|
||||
struct WBArg *am_ArgList; /* array of file references */
|
||||
/* ... */
|
||||
};
|
||||
|
||||
RemoveAppWindow(appwin);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- NDK39: `workbench/workbench.h`, `workbench/startup.h`
|
||||
Loading…
Add table
Add a link
Reference in a new issue