177 lines
9.1 KiB
C
177 lines
9.1 KiB
C
// Part of JoeyLib, Copyright (c) 2026 Scott Duensing, under the MIT License.
|
|
// See LICENSE.md for license information.
|
|
// SPDX-License-Identifier: MIT
|
|
//
|
|
// Serial communications add-on -- portable RS-232 byte streams.
|
|
//
|
|
// OPTIONAL add-on: this header is NOT pulled in by <joey/joey.h>. Include it
|
|
// explicitly. An app that never references jlSerial* pays nothing -- the
|
|
// linker drops the module (archive granularity / IIgs dead-strip).
|
|
//
|
|
// One byte-stream API spans every port; the per-port HAL hides the very
|
|
// different hardware:
|
|
// Apple IIgs -- direct Zilog 8530 SCC (modem/printer ports) or a 6551
|
|
// Super Serial Card in a slot; its own RX interrupt fills
|
|
// the ring (a card needs its interrupt switch, SW2-6, on).
|
|
// DOS -- 8250/16550 UART on a COM port; interrupt-driven RX ring.
|
|
// Amiga -- serial.device (async exec IO); the OS buffers RX.
|
|
// Atari ST -- BIOS Aux (Modem port) via XBIOS Rsconf; TOS buffers RX.
|
|
// X68000 -- SCC channel A: Human68k's RSDRV.SYS for transmit and line
|
|
// setup (75-38400 bps, RTS/CTS), REQUIRED -- the open fails
|
|
// without it; its own RX interrupt fills the ring (when
|
|
// opened in supervisor mode, as jlInit leaves every program).
|
|
// DVX -- a COM port through DVX's serial library.
|
|
// Win32/16 -- a COM port through Windows' communications calls.
|
|
// SDL3 (Linux), Haiku, BeOS -- a terminal device through termios
|
|
// (JOEYLIB_SERIAL in the environment names the default one).
|
|
// The web and the PSP have no serial port.
|
|
//
|
|
// Model: non-blocking + buffered. Received bytes accumulate in a background
|
|
// ring (a hardware IRQ on DOS, the X68000 and the IIgs, the OS on Amiga/ST,
|
|
// DVX, Windows, Linux, Haiku, and BeOS); jlSerialRead / jlSerialAvailable
|
|
// never block. Call
|
|
// jlSerialPoll() once per game frame. Transmit never waits long: a bounded
|
|
// poll on most ports, a queue on the Amiga and Win16.
|
|
//
|
|
// Received bytes CAN be lost. Each port's receive hardware holds 1 to 3 bytes
|
|
// (16 on a 16550), ~1-3 ms at 9600 baud, and anything that keeps interrupts off
|
|
// longer drops what arrives meanwhile. JoeyLib's own work is safe with a port
|
|
// open (on the IIgs it cuts its long interrupts-off stretches to ~1.7 ms while
|
|
// one is), but these are not: IIgs disk access (GS/OS holds interrupts off
|
|
// 65-220 ms per 3.5" floppy access, so every file call, asset load and
|
|
// jlInit, which reads the audio replayer), IIgs jlAudioPlayMod (~12 ms per
|
|
// KB of samples), a Super Serial Card above 2400 baud, and the program's own
|
|
// interrupt masking. Disk access on the other ports is unmeasured. Schedule
|
|
// them between messages, pause the peer first (jlSerialSetRts(false) or
|
|
// XOFF), or use a protocol that retransmits. docs/ApiSerial.adoc, "What Can
|
|
// Lose Received Bytes", has the per-port table.
|
|
//
|
|
// A failed jlSerialOpen is non-fatal: it returns false and every other call is
|
|
// a safe no-op (Available 0, Read 0), exactly like a failed audio init.
|
|
|
|
#ifndef JOEYLIB_SERIAL_H
|
|
#define JOEYLIB_SERIAL_H
|
|
|
|
#include "platform.h"
|
|
#include "types.h"
|
|
|
|
// Which physical interface to open. The IIgs is the oddball with three:
|
|
// JL_SERIAL_MODEM -- IIgs modem port (SCC channel B). Elsewhere == DEFAULT.
|
|
// JL_SERIAL_PRINTER -- IIgs printer port (SCC channel A). Only the IIgs has
|
|
// a second built-in port; elsewhere == DEFAULT.
|
|
// JL_SERIAL_SLOT -- a card/port selected by jlSerialConfigT.unit: IIgs
|
|
// Super Serial Card slot (1..7); DOS or DVX COM number
|
|
// (1..4); Win16 COM (1..9); Win32 COM (1..255); Amiga
|
|
// serial.device unit; Linux /dev/ttyS<unit-1>; Haiku
|
|
// and BeOS the unit'th /dev/ports entry; ST family
|
|
// TOS Bconmap port (1 the Modem port; 2.. a Mega STe's,
|
|
// TT's, or Falcon's others). The X68000 has one port
|
|
// and opens it for every device.
|
|
// JL_SERIAL_DEFAULT -- the platform's natural RS-232 port (IIgs modem, DOS,
|
|
// DVX, and Windows COM1, ST Modem port, Amiga unit 0,
|
|
// X68000 RS-232C, Linux /dev/ttyS0, Haiku and BeOS
|
|
// the first /dev/ports entry).
|
|
typedef enum {
|
|
JL_SERIAL_DEFAULT = 0,
|
|
JL_SERIAL_MODEM,
|
|
JL_SERIAL_PRINTER,
|
|
JL_SERIAL_SLOT
|
|
} jlSerialDeviceE;
|
|
|
|
typedef enum {
|
|
JL_SERIAL_PARITY_NONE = 0,
|
|
JL_SERIAL_PARITY_ODD,
|
|
JL_SERIAL_PARITY_EVEN
|
|
} jlSerialParityE;
|
|
|
|
typedef enum {
|
|
JL_SERIAL_FLOW_NONE = 0, // no handshaking
|
|
JL_SERIAL_FLOW_RTSCTS, // hardware RTS/CTS
|
|
JL_SERIAL_FLOW_XONXOFF // software XON/XOFF
|
|
} jlSerialFlowE;
|
|
|
|
// Line configuration. `unit` disambiguates JL_SERIAL_SLOT (see jlSerialDeviceE)
|
|
// and is ignored for the other devices. A field left 0 takes a default (baud
|
|
// 9600, 8 data bits, 1 stop bit); data bits outside 5..8, stop bits other
|
|
// than 1 or 2, or a parity or flow the enums do not name fail the open.
|
|
typedef struct {
|
|
uint32_t baud; // 300 .. 115200 (each port runs at the nearest rate it has: docs/ApiSerial.adoc)
|
|
uint8_t dataBits; // 5 .. 8
|
|
uint8_t stopBits; // 1 or 2
|
|
jlSerialParityE parity;
|
|
jlSerialFlowE flow;
|
|
uint8_t unit; // JL_SERIAL_SLOT: IIgs slot 1..7 / DOS, DVX COM 1..4 / Win16 COM 1..9 / Win32 COM 1..255 / Amiga unit / ST Bconmap port 1..
|
|
} jlSerialConfigT;
|
|
|
|
// Open + configure the port. Only one port is open at a time; a second
|
|
// jlSerialOpen without a jlSerialClose fails. Returns false (non-fatal) if the
|
|
// port cannot be opened or the platform has no serial support -- every other
|
|
// call then no-ops. It also fails, with jlLastError() saying why, when no UART
|
|
// answers at the DOS COM port, when no Super Serial Card answers in the IIgs
|
|
// slot, and when RSDRV.SYS is not loaded on the X68000.
|
|
bool jlSerialOpen(jlSerialDeviceE device, const jlSerialConfigT *config);
|
|
|
|
// Close the open port and release its resources. Safe to call when not open.
|
|
// Bytes jlSerialWrite accepted are still sent.
|
|
// A port still open when the program exits is closed then (the first
|
|
// successful jlSerialOpen registers an atexit handler): where the port's RX
|
|
// interrupt is taken over (DOS, X68000, IIgs), the vector points into the
|
|
// program until it is closed.
|
|
//
|
|
// Closing does NOT hang up: DTR is left exactly as it was, so a modem call or a
|
|
// BBS caller survives a program handing the line back -- a door returning to
|
|
// its BBS, a terminal exiting. RTS is not part of that promise (on the Amiga,
|
|
// serial.device puts back what it found at open). To hang up, drop DTR with
|
|
// jlSerialSetDtr(false), wait longer than the modem's DTR-drop detection time
|
|
// (Hayes S25: 50 ms by default), then close: the line stays down.
|
|
void jlSerialClose(void);
|
|
|
|
// Pump the RX/TX buffers. Call once per game frame.
|
|
void jlSerialPoll(void);
|
|
|
|
// Bytes waiting in the RX buffer, readable now without blocking.
|
|
uint16_t jlSerialAvailable(void);
|
|
|
|
// Copy up to `max` received bytes into `buf`; returns the count copied
|
|
// (0 .. max). Never blocks.
|
|
uint16_t jlSerialRead(uint8_t *buf, uint16_t max);
|
|
|
|
// Send `len` bytes; returns the count accepted (may be < len if a flow-
|
|
// controlled peer or a full transmit path stalls). Never waits long: a
|
|
// bounded poll on most ports; the Amiga and Win16 queue instead.
|
|
uint16_t jlSerialWrite(const uint8_t *buf, uint16_t len);
|
|
|
|
// Single-byte convenience. jlSerialReadByte returns -1 when none is ready.
|
|
bool jlSerialWriteByte(uint8_t b);
|
|
int16_t jlSerialReadByte(void);
|
|
|
|
// Discard any buffered received bytes.
|
|
void jlSerialFlush(void);
|
|
|
|
// RAISE OR DROP DTR -- how a program hangs up.
|
|
//
|
|
// jlSerialOpen raises DTR and jlSerialClose leaves it as it is, so this is the one call that drops
|
|
// it. To hang up a modem: jlSerialSetDtr(false), wait longer than the modem's DTR-drop detection
|
|
// time (Hayes S25: 50 ms by default), then jlSerialClose -- the line stays down. `on` = true raises
|
|
// it again.
|
|
//
|
|
// Two ports tie DTR to more than the line. An IIgs Super Serial Card's 6551 has no separate DTR
|
|
// bit: dropping DTR also stops the card's receiver until DTR is raised again. On the X68000 the
|
|
// line setup in the ROM and in RSDRV.SYS raises DTR whenever it runs, so the next jlSerialOpen
|
|
// (or anything else that sets the line) raises it again. A closed port no-ops, so a caller can
|
|
// drive it unconditionally.
|
|
void jlSerialSetDtr(bool on);
|
|
|
|
// ASSERT OR DROP RTS, for a caller that does its own receive-side flow control.
|
|
//
|
|
// JL_SERIAL_FLOW_RTSCTS asks the PORT to handshake; this is the other half - the application saying
|
|
// "my buffer is nearly full, stop sending" and later "go ahead", which is what a client with a small
|
|
// ring and a peer that can be told to pause actually needs. RetroNet's 6551 clients (C64, Apple II)
|
|
// have done exactly this for a long time and the 16-bit tier could not, so a JoeyLib target's only
|
|
// defense against an overrun was the packet layer's retransmit.
|
|
//
|
|
// `on` = true asserts RTS (ready to receive). A port with no controllable RTS line no-ops, and a
|
|
// closed port no-ops; neither is an error, so a caller can drive it unconditionally.
|
|
void jlSerialSetRts(bool on);
|
|
|
|
#endif
|