Catalyst

Hardware-accelerated TCP/IP and TLS offload library for classic Amiga — a drop-in bsdsocket.library replacement backed by a network coprocessor.

Catalyst moves the entire TCP/IP stack, and TLS/SSL termination, off the 68k CPU and onto dedicated coprocessor hardware. The Amiga writes socket requests into a memory-mapped mailbox; the coprocessor does the networking and crypto. Existing Amiga network software runs unmodified, and HTTPS — historically punishing on a 68k because of the TLS handshake crypto — becomes fast because the cryptography runs in hardware.

Status: early development. Not yet functional. This repository currently contains the library scaffolding and architecture. See Status below.

---

Why

On a stock Amiga, running a TCP/IP stack natively burdens the CPU, and HTTPS is worse still: the TLS handshake's public-key cryptography (RSA/ECC) can stall a 68k for seconds. Catalyst's approach is to make the Amiga think it is reading and writing fast local memory, while a coprocessor handles the network stack and TLS termination in the background. The 68k only ever pokes a mailbox; it never runs a TCP state machine, computes a checksum, or performs a handshake.

What it provides

• bsdsocket.library — a drop-in replacement implementing the standard Amiga BSD-sockets API. Existing networked applications (browsers, FTP, mail, BBS clients) work unmodified and are transparently offloaded.
• catalyst.library — an extension library exposing capabilities the standard sockets API cannot express: TLS-terminated connections (open a secure connection, read/write plaintext while the coprocessor handles the crypto), certificate/verification inspection, and link status. Intended for new or adapted TLS-aware applications.

Both libraries are thin API layers over the same underlying offload engine.

Architecture

Catalyst is the Amiga-side software only. It is deliberately independent of any specific card or coprocessor. It talks to hardware through a small, fixed mailbox contract; everything below that contract (the coprocessor, its firmware, the radio or wired interface) lives in separate, hardware-specific projects.

  Amiga application
        |
        +-- bsdsocket.library   (standard API, transparent offload)
        +-- catalyst.library    (TLS-aware / extended API)
                |
        +-------+--------+
        |  common layer   |   target-independent: library scaffolding,
        |  (src/common)   |   socket/TLS API, command-block marshalling
        +-------+--------+
                |  mailbox_hal.h  (the contract -- move bytes + signal)
        +-------+--------+
        |  HAL (src/hal)  |   one thin file per card type
        +-------+--------+
                |
         [ mailbox / coprocessor ]   <- defined by PROTOCOL.md, implemented
                                        by the firmware (separate repo)

The split that matters: ~95% of the code is target-independent (the TLS logic, the socket marshalling, the command-block protocol, the library scaffolding). The only per-card difference is the thin HAL layer that knows how to read/write the mailbox and signal the coprocessor on a given bus. New card types are added by writing one new HAL file — not by branching or forking the codebase.

Supported / planned targets

The same library runs across multiple card types by selecting a HAL at build time. The SF2000 accelerator is the primary, actively-developed target; the others are possibilities the architecture allows and that other people could contribute, rather than commitments by this project.

Target	HAL file	Amiga interface	Status
SF2000	hal_sf2000.c	accelerator local bus (via FPGA)	primary
A600/A1200	hal_pcmcia.c	PCMCIA (Gayle-mapped window)	possible
Clockport	hal_clockport.c	clockport fixed-address window	possible

The SF2000 already covers the A500: it installs on the A500 86-pin edge expansion via the POC86 adapter, so a dedicated edge-connector HAL is not planned here. If someone builds a standalone edge-connector card, adding a HAL for it is a matter of one new hal_*.c file -- the rest of the library is unchanged.

Repository layout

catalyst/
  include/
    catalyst.h          public catalyst.library API
    bsdsocket_proto.h   bsdsocket LVO definitions
    mailbox_hal.h       the HAL contract every target implements
  src/
    common/             target-independent code
      library.c         romtag, open/close/expunge
      catalyst_api.c    CatOpenSecure / CatSend / CatRecv / ...
      bsdsocket_api.c   bsdsocket vector implementations
      marshal.c         command-block protocol over the HAL
    hal/
      hal_sf2000.c      SF2000 transport
      hal_*.c           other targets
  Makefile              selects HAL via a TARGET flag
  PROTOCOL.md           the mailbox contract (firmware <-> Amiga)
  README.md

Building

Catalyst builds with a modern m68k GCC cross-toolchain (Bartman's amiga-elf GCC or Bebbo's amiga-gcc). A target is selected at compile time:

make TARGET=sf2000        # build for the SF2000 accelerator

The output libraries are placed in LIBS: on the target Amiga.

Toolchain note (GCC 15.x): building Amiga shared libraries with GCC 15.x requires (a) the register-parameter (regparm) support so library entry points receive arguments in the correct registers, and (b) regenerated NDK headers that emit correct inline library-call stubs. See the build instructions for details.

Relationship to other repositories

• This repo (catalyst): the Amiga-side library, including the HAL for each card. Hardware-independent above the HAL boundary.
• Firmware repos (e.g. SF2000-FW): the coprocessor-side code (network stack driver, TLS coprocessor link, mailbox implementation on the hardware side). Card-specific.
• PROTOCOL.md: the mailbox contract both sides honor. The Amiga HAL implements one side; the firmware implements the other.

Status

Early development; not yet usable. Rough order of work:

• Do-nothing catalyst.library that loads and dispatches a stub call
• Skeleton bsdsocket.library (correct LVO layout, stub functions)
• mailbox_hal.h contract finalized
• hal_sf2000.c first transport implementation
• marshal.c command-block protocol
• First real raw-TCP connection through the engine
• First TLS-terminated connection (HTTPS) through the engine
• bsdsocket API coverage sufficient for existing apps
• catalyst.library TLS API for adapted applications

First milestone: the library loads and dispatches

The do-nothing catalyst.library loads via Exec's romtag scanner, refcounts opens/closes correctly, and dispatches a call through its vector table. The test_catalyst program opens the library, calls CatVersion through the library base, and closes; the KPrintF serial trace (left) shows the matching lifecycle — init_lib once, then open_lib / CatVersion called / close_lib.

License

LGPL-2.1. See LICENSE.

The lesser/library GPL is used deliberately so that applications — including closed-source and commercial ones, such as existing Amiga web browsers — can link bsdsocket.library and catalyst.library and benefit from transparent offload, while modifications to the libraries themselves (and contributed HALs) remain open.