From 04dc47664be6f996a117298b4adaa299a72372fc Mon Sep 17 00:00:00 2001 From: "Rich O." Date: Mon, 2 Nov 2026 10:44:19 -0500 Subject: [PATCH] palm-client: interrupt-driven SB-LoRa receive (slot IRQ handler drains the SC16IS740 into a ring) --- docs/progress.md | 1 + palm-client/src/hs_card.h | 9 +++ palm-client/src/sb_spi.c | 131 ++++++++++++++++++++++---------- palm-client/src/sb_spi.h | 32 ++++++++ palm-client/src/transport_sb.c | 120 +++++++++++++++++++++++++---- palm-client/tests/test_sblora.c | 60 +++++++++++++++ 6 files changed, 298 insertions(+), 55 deletions(-) diff --git a/docs/progress.md b/docs/progress.md index a2f29b5..454d34b 100644 --- a/docs/progress.md +++ b/docs/progress.md @@ -81,3 +81,4 @@ - 2026-11-02: SB-LoRa transport written ahead of the boards: bus-SPI bit-bang over CS0/CS1 (`sb_spi.c`), SC16IS740 setup for 115200 8N1, burst FIFO access, sleep, and a "Slot" link on the Node screen (`transport_sb.c`). `tests/test_sblora.c` checks it against a simulated carrier (latches, inverter, SC16IS740). Unknowns for bring-up: whether connector A0 is CPU A1 (the probe tries both mappings via the scratch register), the hard-coded csSlot0 base 0x28000000 (no Handspring SDK for HsCardAttrGet), and RX overruns while the app isn't polling (no IRQ handler yet). Segments: 9.6 / 27.7 / 13.1 KB. - 2026-11-02: Slot with an empty slot reset the Visor (bus error at csSlot0), and since Slot was saved and Home auto-connects, every launch reset it. Slot is no longer restored at launch, and Connect now checks `HsCardAttrGet(hsCardAttrHwInstalled)` and takes the chip-select base and size from the OS before any bus access. Verified on the Neo: empty slot gives "No module in the slot." with no reset. Node-screen errors shortened to its 22-character labels. - 2026-11-02: Notification sounds (Options > Sounds): separate tunes for direct messages, mentions, room posts, private / hashtag / Public channels and new contacts (PUSH_NEW_ADVERT), each on or off, at the alarm volume. One sound per poll, by priority; none for the conversation on screen. Verified on the Neo. Segment 3 is 13.8 KB. +- 2026-11-02: SB-LoRa receive is interrupt-driven: a slot IRQ* handler (hsCardAttrIntHandler) drains the SC16IS740 RX FIFO (IER RHR, trigger 8 or timeout) into a 1 KB ring passed as cardParam. The handler path (SbDrainRx and the bus core) is in segment 1 with no A5 references, checked in the disassembly, so it's safe in interrupt context and while the Visor sleeps. The app masks the slot interrupt around its own SPI transactions, and falls back to polling if the handler won't install. Host tests cover draining, ring wrap and overflow; untested on hardware. diff --git a/palm-client/src/hs_card.h b/palm-client/src/hs_card.h index 51245f9..1e1f554 100644 --- a/palm-client/src/hs_card.h +++ b/palm-client/src/hs_card.h @@ -18,8 +18,15 @@ #define hsCardAttrHwInstalled 1 /* UInt8: module present and out of reset */ #define hsCardAttrCsBase 3 /* UInt32: csSlot0 address */ #define hsCardAttrCsSize 4 /* UInt32: size of each chip select */ +#define hsCardAttrIntEnable 7 /* UInt8: slot IRQ* enabled (off by default) */ +#define hsCardAttrCardParam 8 /* UInt32: passed to the handlers */ +#define hsCardAttrIntHandler 9 /* HsCardIntHandlerPtr */ + +/* Called on IRQ* (level, active low); *sysAwakeP false = only memory accesses allowed. */ +typedef void (*HsCardIntHandlerPtr)(UInt32 cardParam, Boolean *sysAwakeP); #define hsSelCardAttrGet 0x6 +#define hsSelCardAttrSet 0x7 /* Two levels so table/vector/selector are macro-expanded before _Str. */ #define VM_HS_CALL(table, vector, selector) \ @@ -30,5 +37,7 @@ Err HsCardAttrGet(UInt16 cardNo, UInt16 attr, void *valueP) VM_HS_SEL_TRAP(sysTrapOEMDispatch, hsSelCardAttrGet); +Err HsCardAttrSet(UInt16 cardNo, UInt16 attr, void *valueP) + VM_HS_SEL_TRAP(sysTrapOEMDispatch, hsSelCardAttrSet); #endif diff --git a/palm-client/src/sb_spi.c b/palm-client/src/sb_spi.c index 21355c4..e4f1eb7 100644 --- a/palm-client/src/sb_spi.c +++ b/palm-client/src/sb_spi.c @@ -1,24 +1,28 @@ #include "sb_spi.h" -static UInt8 Xfer(UInt8 out) VM_SECT3; -static void Select(void) VM_SECT3; -static void Deselect(void) VM_SECT3; +/* + * The bus core (Xfer to BusReadFifo) and SbDrainRx stay in the first segment + * and use only the SbBus they're given: the interrupt handler runs them, and + * it can't reach globals or call into vmcode3 (both need A5). + */ +static UInt8 Xfer(const SbBus *b, UInt8 out); +static void Select(const SbBus *b); +static void Deselect(const SbBus *b); +static UInt8 BusReadReg(const SbBus *b, UInt8 reg); +static void BusReadFifo(const SbBus *b, UInt8 *buf, UInt16 n); static Boolean ScratchOk(void) VM_SECT3; -static UInt32 gCs0 = SB_CS0_BASE; -static UInt32 gCs1 = SB_CS0_BASE + SB_CS_SIZE; -static UInt32 gOffNcs; /* byte offset that drives connector A17 */ -static UInt32 gOffMosi; /* ... and A8 */ +static SbBus gBus = { SB_CS0_BASE, SB_CS0_BASE + SB_CS_SIZE, 0, 0 }; /* nCS = NOT A17: an access with A17 high selects the chip. */ -static void Select(void) +static void Select(const SbBus *b) { - (void)SB_BUS_READ(gCs0 + gOffNcs); + (void)SB_BUS_READ(b->cs0 + b->offNcs); } -static void Deselect(void) +static void Deselect(const SbBus *b) { - (void)SB_BUS_READ(gCs0); + (void)SB_BUS_READ(b->cs0); } /* @@ -26,55 +30,100 @@ static void Deselect(void) * low; the CS1 read raises SCLK, where the chip samples MOSI, and returns * MISO, which only changes on the falling edge after it. */ -static UInt8 Xfer(UInt8 out) +static UInt8 Xfer(const SbBus *b, UInt8 out) { - UInt32 sel = gCs0 + gOffNcs; + UInt32 sel = b->cs0 + b->offNcs; + UInt32 clk = b->cs1; UInt8 in = 0; UInt8 mask; for (mask = 0x80; mask; mask >>= 1) { - (void)SB_BUS_READ((out & mask) ? sel : sel + gOffMosi); - in = (UInt8)((in << 1) | (SB_BUS_READ(gCs1) & 1)); + (void)SB_BUS_READ((out & mask) ? sel : sel + b->offMosi); + in = (UInt8)((in << 1) | (SB_BUS_READ(clk) & 1)); } return in; } /* Register byte: bit 7 = read, bits 6:3 = register, bits 2:1 = channel 0. */ -UInt8 SbReadReg(UInt8 reg) +static UInt8 BusReadReg(const SbBus *b, UInt8 reg) { UInt8 val; - Select(); - Xfer((UInt8)(0x80 | (reg << 3))); - val = Xfer(0); - Deselect(); + Select(b); + Xfer(b, (UInt8)(0x80 | (reg << 3))); + val = Xfer(b, 0); + Deselect(b); return val; } +static void BusReadFifo(const SbBus *b, UInt8 *buf, UInt16 n) +{ + Select(b); + Xfer(b, 0x80 | (SB_RHR << 3)); + while (n--) + *buf++ = Xfer(b, 0); + Deselect(b); +} + +UInt8 SbReadReg(UInt8 reg) +{ + return BusReadReg(&gBus, reg); +} + void SbWriteReg(UInt8 reg, UInt8 val) { - Select(); - Xfer((UInt8)(reg << 3)); - Xfer(val); - Deselect(); + Select(&gBus); + Xfer(&gBus, (UInt8)(reg << 3)); + Xfer(&gBus, val); + Deselect(&gBus); } void SbWriteFifo(const UInt8 *buf, UInt16 n) { - Select(); - Xfer(SB_THR << 3); + Select(&gBus); + Xfer(&gBus, SB_THR << 3); while (n--) - Xfer(*buf++); - Deselect(); + Xfer(&gBus, *buf++); + Deselect(&gBus); } void SbReadFifo(UInt8 *buf, UInt16 n) { - Select(); - Xfer(0x80 | (SB_RHR << 3)); - while (n--) - *buf++ = Xfer(0); - Deselect(); + BusReadFifo(&gBus, buf, n); +} + +const SbBus *SbCurrentBus(void) +{ + return &gBus; +} + +/* + * Empties the RX FIFO into the ring, which also releases the chip's IRQ + * (it's level-triggered). Bytes that don't fit are read and dropped. + */ +void SbDrainRx(SbRing *r) +{ + UInt8 drop[SB_FIFO_SIZE]; + UInt16 n, head, room, toEnd; + + while ((n = BusReadReg(&r->bus, SB_RXLVL)) != 0) { + if (n > SB_FIFO_SIZE) + n = SB_FIFO_SIZE; + head = r->head; + room = SB_RING_SIZE - (UInt16)(head - r->tail); + if (room == 0) { + BusReadFifo(&r->bus, drop, n); + r->overflow = true; + continue; + } + toEnd = SB_RING_SIZE - (head & (SB_RING_SIZE - 1)); + if (n > room) + n = room; + if (n > toEnd) + n = toEnd; + BusReadFifo(&r->bus, r->buf + (head & (SB_RING_SIZE - 1)), n); + r->head = head + n; + } } static Boolean ScratchOk(void) @@ -88,8 +137,8 @@ static Boolean ScratchOk(void) void SbSetBase(UInt32 cs0, UInt32 csSize) { - gCs0 = cs0; - gCs1 = cs0 + csSize; + gBus.cs0 = cs0; + gBus.cs1 = cs0 + csSize; } Boolean SbProbe(void) @@ -98,15 +147,15 @@ Boolean SbProbe(void) /* Connector A0 = CPU A1 first: the slot only does 16-bit, even-address cycles. */ for (shift = 1; ; shift--) { - gOffNcs = 1UL << (17 + shift); - gOffMosi = 1UL << (8 + shift); - Deselect(); + gBus.offNcs = 1UL << (17 + shift); + gBus.offMosi = 1UL << (8 + shift); + Deselect(&gBus); if (ScratchOk()) return true; if (shift == 0) break; } - Deselect(); + Deselect(&gBus); return false; } @@ -117,8 +166,8 @@ void SbUartInit(void) SbWriteReg(SB_DLL, 8); /* 14.7456 MHz / (16 * 8) = 115200 */ SbWriteReg(SB_DLH, 0); SbWriteReg(SB_LCR, 0x03); /* 8N1 */ - SbWriteReg(SB_FCR, 0x07); /* FIFOs on, both reset */ - SbWriteReg(SB_IER, 0x00); /* polled */ + SbWriteReg(SB_FCR, 0x07); /* FIFOs on, both reset; RX trigger at 8 */ + SbWriteReg(SB_IER, 0x00); /* interrupts off until a handler is in */ } /* Sleep mode is an enhanced function: EFR bit 4 must be set to change IER bit 4. */ diff --git a/palm-client/src/sb_spi.h b/palm-client/src/sb_spi.h index 478e3e5..86dd890 100644 --- a/palm-client/src/sb_spi.h +++ b/palm-client/src/sb_spi.h @@ -41,6 +41,28 @@ #define SB_EFR 0x02 #define SB_FIFO_SIZE 64 +#define SB_IER_RHR 0x01 /* IER: interrupt on RX data (trigger level or timeout) */ + +/* Where the chip is on the bus: chip-select addresses and the A17/A8 offsets. */ +typedef struct { + UInt32 cs0, cs1; + UInt32 offNcs; /* byte offset that drives connector A17 */ + UInt32 offMosi; /* ... and A8 */ +} SbBus; + +/* + * Received bytes, filled by the interrupt handler (SbDrainRx) and read by the + * app. head is only written by the handler and tail only by the app, so the + * two need no locking (16-bit writes are atomic on the 68k). + */ +#define SB_RING_SIZE 1024 /* a power of two */ +typedef struct { + SbBus bus; /* a copy, so the handler needs no globals */ + volatile UInt16 head; + volatile UInt16 tail; + volatile Boolean overflow; /* bytes were dropped */ + UInt8 buf[SB_RING_SIZE]; +} SbRing; /* * Finds the module by writing and reading back the scratch register. The @@ -55,6 +77,16 @@ void SbSetBase(UInt32 cs0, UInt32 csSize) VM_SECT3; /* 115200 8N1 (14.7456 MHz crystal, DLL = 8), FIFOs on, interrupts off. */ void SbUartInit(void) VM_SECT3; +/* The bus SbProbe found, to copy into an SbRing. */ +const SbBus *SbCurrentBus(void) VM_SECT3; + +/* + * Moves everything in the RX FIFO into r. Safe in the slot interrupt handler, + * even before the system is awake: it uses only r and plain bus reads, and + * it's in the first segment (no VM_SECT3) so calling it needs no A5. + */ +void SbDrainRx(SbRing *r); + /* Low-power sleep (IER bit 4) while the link is closed, or wake. */ void SbSleep(Boolean sleep) VM_SECT3; diff --git a/palm-client/src/transport_sb.c b/palm-client/src/transport_sb.c index 9ef6068..2951a63 100644 --- a/palm-client/src/transport_sb.c +++ b/palm-client/src/transport_sb.c @@ -1,9 +1,14 @@ /* - * Transport over the SB-LoRa Springboard module (sb_spi.c). Polled: the - * SC16IS740's 64-byte RX FIFO fills in about 5.5 ms at 115200, so bytes that - * arrive while the app isn't inside TransportRecv can be lost. An interrupt - * handler on the slot IRQ* (wired to the chip's IRQ) would fix that, through - * hsCardAttrIntHandler (not done yet). + * Transport over the SB-LoRa Springboard module (sb_spi.c). + * + * Receiving is interrupt-driven: the SC16IS740 raises the slot IRQ* when its + * RX FIFO reaches 8 bytes or goes quiet, and SbIntHandler drains it into + * gRing. Without the handler the 64-byte FIFO lasts about 5.5 ms at 115200, + * so anything that arrived while the app was busy elsewhere was lost. If the + * handler can't be installed, it falls back to polling the FIFO. + * + * The handler and the app share the bus, so the app masks the slot interrupt + * around its own SPI transactions (sends, close). */ #include #include "transport.h" @@ -13,6 +18,22 @@ #define SB_SEND_TICKS 200 /* give up if the TX FIFO doesn't drain for 2 s */ static Boolean gOpen = false; +static Boolean gIrq = false; /* the interrupt handler is installed */ +static SbRing gRing; + +/* Interrupt context: no globals (gRing comes in as cardParam), no system calls. */ +static void SbIntHandler(UInt32 cardParam, Boolean *sysAwakeP) +{ + (void)sysAwakeP; /* draining needs only bus reads, so the Visor can stay asleep */ + SbDrainRx((SbRing *)cardParam); +} + +static Boolean ModuleInstalled(void) +{ + UInt8 installed = 0; + + return HsCardAttrGet(hsCardSlot, hsCardAttrHwInstalled, &installed) == errNone && installed; +} /* * Asks the OS whether a module is in the slot and where its chip selects @@ -21,11 +42,10 @@ static Boolean gOpen = false; static Boolean ModulePresent(void) { UInt32 version, base, size; - UInt8 installed = 0; if (FtrGet(hsFtrCreator, hsFtrIDVersion, &version) != errNone) return false; /* not a Handspring device: no slot */ - if (HsCardAttrGet(hsCardSlot, hsCardAttrHwInstalled, &installed) != errNone || !installed) + if (!ModuleInstalled()) return false; if (HsCardAttrGet(hsCardSlot, hsCardAttrCsBase, &base) != errNone || HsCardAttrGet(hsCardSlot, hsCardAttrCsSize, &size) != errNone) @@ -34,6 +54,46 @@ static Boolean ModulePresent(void) return true; } +static void IrqEnable(Boolean on) +{ + UInt8 enable = on; + + if (gIrq) + HsCardAttrSet(hsCardSlot, hsCardAttrIntEnable, &enable); +} + +static Boolean InstallHandler(void) +{ + UInt32 param = (UInt32)&gRing; + HsCardIntHandlerPtr handler = SbIntHandler; + UInt8 enable = true; + + gRing.bus = *SbCurrentBus(); + gRing.head = gRing.tail = 0; + gRing.overflow = false; + if (HsCardAttrSet(hsCardSlot, hsCardAttrCardParam, ¶m) != errNone || + HsCardAttrSet(hsCardSlot, hsCardAttrIntHandler, &handler) != errNone) + return false; + SbWriteReg(SB_IER, SB_IER_RHR); + /* interrupts start disabled; the guide says to enable them after installing */ + if (HsCardAttrSet(hsCardSlot, hsCardAttrIntEnable, &enable) != errNone) { + SbWriteReg(SB_IER, 0); + handler = NULL; + HsCardAttrSet(hsCardSlot, hsCardAttrIntHandler, &handler); + return false; + } + return true; +} + +static void RemoveHandler(void) +{ + HsCardIntHandlerPtr handler = NULL; + + IrqEnable(false); + HsCardAttrSet(hsCardSlot, hsCardAttrIntHandler, &handler); + gIrq = false; +} + Err SbTransportOpen(void) { if (gOpen) @@ -41,6 +101,7 @@ Err SbTransportOpen(void) if (!ModulePresent() || !SbProbe()) return vmErrNoModule; SbUartInit(); + gIrq = InstallHandler(); gOpen = true; return errNone; } @@ -49,7 +110,10 @@ void SbTransportClose(void) { if (!gOpen) return; - SbSleep(true); + if (gIrq) + RemoveHandler(); + if (ModuleInstalled()) /* pulled out: the bus is gone */ + SbSleep(true); gOpen = false; } @@ -60,16 +124,22 @@ Err SbTransportSend(const UInt8 *buf, UInt16 len) if (!gOpen) return serErrNotOpen; + if (!ModuleInstalled()) + return vmErrNoModule; while (len) { + /* one FIFO's worth per masked stretch, so the handler gets in between */ + IrqEnable(false); n = SbReadReg(SB_TXLVL); + if (n > len) + n = len; + if (n) + SbWriteFifo(buf, n); + IrqEnable(true); if (n == 0) { if (TimGetTicks() >= deadline) return serErrTimeOut; continue; } - if (n > len) - n = len; - SbWriteFifo(buf, n); buf += n; len -= n; deadline = TimGetTicks() + SB_SEND_TICKS; @@ -77,10 +147,24 @@ Err SbTransportSend(const UInt8 *buf, UInt16 len) return errNone; } +static UInt16 RingRead(UInt8 *buf, UInt16 max) +{ + UInt16 head = gRing.head; + UInt16 n = 0; + + while (gRing.tail != head && n < max) { + buf[n++] = gRing.buf[gRing.tail & (SB_RING_SIZE - 1)]; + gRing.tail++; + } + /* a dropped stretch shows up as a bad frame, which the decoder skips */ + gRing.overflow = false; + return n; +} + /* - * Busy-polls RXLVL until data or the timeout, then keeps reading while the - * FIFO has more, up to max. Busy rather than SysTaskDelay: a one-tick sleep - * is longer than the FIFO lasts. + * With the handler, waits on the ring (a tick at a time: it fills on its own). + * Without it, busy-polls RXLVL, since a one-tick sleep is longer than the FIFO + * lasts, then keeps reading while the FIFO has more, up to max. */ UInt16 SbTransportRecv(UInt8 *buf, UInt16 max, Int32 timeoutTicks, Err *errP) { @@ -93,6 +177,14 @@ UInt16 SbTransportRecv(UInt8 *buf, UInt16 max, Int32 timeoutTicks, Err *errP) *errP = serErrNotOpen; return 0; } + if (gIrq) { + while (gRing.head == gRing.tail) { + if (TimGetTicks() >= deadline) + return 0; + SysTaskDelay(1); + } + return RingRead(buf, max); + } for (;;) { n = SbReadReg(SB_RXLVL); if (n) diff --git a/palm-client/tests/test_sblora.c b/palm-client/tests/test_sblora.c index 42ee521..ba922db 100644 --- a/palm-client/tests/test_sblora.c +++ b/palm-client/tests/test_sblora.c @@ -207,6 +207,65 @@ static void test_sleep(void) CHECK(regs[SB_IER] == 0); } +static void inject(int n, UInt8 first) +{ + int i; + + for (i = 0; i < n; i++) + rxq[rxn + i] = (UInt8)(first + i); + rxn = (UInt8)(rxn + n); +} + +static void test_drain(void) +{ + static SbRing r; + int i, before; + + SimInsert(1); + CHECK(SbProbe()); + SbUartInit(); + memset(&r, 0, sizeof(r)); + r.bus = *SbCurrentBus(); + + /* a plain drain empties the FIFO (which is what releases IRQ*) */ + inject(40, 0x10); + SbDrainRx(&r); + CHECK(rxn == 0); + CHECK(r.head == 40 && r.tail == 0 && !r.overflow); + for (i = 0; i < 40; i++) + CHECK(r.buf[i] == (UInt8)(0x10 + i)); + CHECK(ncs); + + /* wraps at the end of the ring */ + r.head = r.tail = SB_RING_SIZE - 10; + inject(30, 0x40); + SbDrainRx(&r); + CHECK(rxn == 0); + CHECK(r.head == (UInt16)(SB_RING_SIZE + 20)); + CHECK(r.buf[SB_RING_SIZE - 10] == 0x40 && r.buf[SB_RING_SIZE - 1] == 0x40 + 9); + CHECK(r.buf[0] == 0x40 + 10 && r.buf[19] == 0x40 + 29); + + /* the counters wrap at 64K too */ + r.head = r.tail = 0xFFFE; + inject(4, 0x60); + SbDrainRx(&r); + CHECK(r.head == 2 && (UInt16)(r.head - r.tail) == 4); + + /* a full ring keeps what fits, drops the rest, and still empties the FIFO */ + r.tail = 0; + r.head = SB_RING_SIZE - 5; + r.overflow = false; + before = transactions; + inject(20, 0x80); + SbDrainRx(&r); + CHECK(rxn == 0); + CHECK(r.head == SB_RING_SIZE); + CHECK(r.overflow); + CHECK(r.buf[SB_RING_SIZE - 5] == 0x80 && r.buf[SB_RING_SIZE - 1] == 0x84); + CHECK(transactions > before); + CHECK(ncs); +} + int main(void) { test_probe(); @@ -214,6 +273,7 @@ int main(void) test_registers(); test_fifos(); test_sleep(); + test_drain(); if (failures) { printf("%d failure(s)\n", failures); return 1;