Use modulo (capacity + 1) instead of (capacity * 2) for UART buffers

Author: object-Object

README.md

@@ -36,8 +36,8 @@ Addresses `0xf0000000` - `0xffffffff` are reserved for system purposes such as M
 
 Addresses `0xf0000010` and `0xf0000030` contain emulated UART 16550 peripherals based on [this datasheet](https://caro.su/msx/ocm_de1/16550.pdf). The UARTs support the following features:
 
-- Configurable FIFO capacity (up to 254 bytes) for TX and RX, stored as a variable in the CONFIG processor.
-- Theoretical maximum transfer rate of 121920 bits/sec (254 bytes/tick).
+- Configurable FIFO capacity (up to 253 bytes) for TX and RX, stored as a variable in the CONFIG processor.
+- Theoretical maximum transfer rate of 121440 bits/sec (253 bytes/tick).
 - Line Status Register flags: Transmitter Empty, THR Empty, Overrun Error, Data Ready.
 - FIFO Control Register flags: Enable FIFOs (0 is ignored), Reset RX/TX FIFO
 
@@ -58,20 +58,18 @@ The UART registers have a stride of 4 bytes to simplify some internal logic.
 
 Each UART is implemented as two circular buffers in a memory bank with the following layout. Note that RX refers to data sent to / read by the processor, and TX refers to data sent from / written by the processor.
 
-| Index | Name                    |
-| ----- | ----------------------- |
-| 0     | RX buffer start         |
-| 254   | RX buffer read pointer  |
-| 255   | RX buffer write pointer |
-| 256   | TX buffer start         |
-| 510   | TX buffer read pointer  |
-| 511   | TX buffer write pointer |
+| Index | Name                                    |
+| ----- | --------------------------------------- |
+| 0     | RX buffer start                         |
+| 254   | RX buffer read pointer                  |
+| 255   | RX buffer write pointer / overflow flag |
+| 256   | TX buffer start                         |
+| 510   | TX buffer read pointer                  |
+| 511   | TX buffer write pointer                 |
 
-Read/write pointers are stored modulo `2 * capacity` ([ref 1](https://github.com/hathach/tinyusb/blob/b203d9eaf7d76fd9fec71b4ee327805a80594574/src/common/tusb_fifo.h), [ref 2](https://gist.github.com/mcejp/719d3485b04cfcf82e8a8734957da06a)) to allow using the entire buffer capacity without introducing race conditions.
+Read/write pointers are stored modulo `capacity + 1`. A buffer is empty when `rptr == wptr` and full when `rptr == (wptr + 1) % (capacity + 1)`. If the RX buffer is full and more data arrives, producers should discard the new data rather than overwriting old data in the buffer. An overflow may optionally be indicated to the processor by setting bit 8 of `rx_wptr` (ie. `rx_wptr | 0x100`).
 
-If the RX buffer is full and more data arrives, producers should discard the new data rather than overwriting old data in the buffer. An overflow may optionally be indicated by advancing the RX write pointer (without writing a value to the buffer) such that the size of the buffer is `capacity + 1`; this must be done atomically (ie. `wait` first) to avoid race conditions.
-
-Note that the processor itself does not prevent code from overflowing the TX buffer. Users are expected to check the Line Status Register and avoid writing too much data at once.
+Note that the processor itself does not set the TX overflow flag or prevent code from overflowing the TX buffer. Users are expected to check the Line Status Register and avoid writing too much data at once.
 
 ### Syscon
 

mod/src/main/kotlin/gay/object/mlogv32/ProcessorAccess.kt

@@ -35,12 +35,12 @@ class ProcessorAccess(
     val resetSwitch: SwitchBuild,
     val pauseSwitch: SwitchBuild,
     val singleStepSwitch: SwitchBuild,
-    val uartFifoCapacity: Int,
+    uartFifoModulo: Int,
     uart0: MemoryBuild,
     uart1: MemoryBuild,
 ) {
-    val uart0 = UartAccess(uart0, uartFifoCapacity)
-    val uart1 = UartAccess(uart1, uartFifoCapacity)
+    val uart0 = UartAccess(uart0, uartFifoModulo - 1)
+    val uart1 = UartAccess(uart1, uartFifoModulo - 1)
 
     val romEnd = ROM_START + romSize.toUInt()
     val ramEnd = RAM_START + ramSize.toUInt()
@@ -253,7 +253,7 @@ class ProcessorAccess(
                 resetSwitch = buildVar<SwitchBuild>(build, "switch1") ?: return null,
                 pauseSwitch = buildVar<SwitchBuild>(build, "switch2") ?: return null,
                 singleStepSwitch = buildVar<SwitchBuild>(build, "switch3") ?: return null,
-                uartFifoCapacity = positiveIntVar(build, "UART_FIFO_CAPACITY") ?: return null,
+                uartFifoModulo = positiveIntVar(build, "UART_FIFO_MODULO") ?: return null,
                 uart0 = buildVar<MemoryBuild>(build, "bank1") ?: return null,
                 uart1 = buildVar<MemoryBuild>(build, "bank2") ?: return null,
             )
@@ -399,16 +399,20 @@ data class UartRequest(
             val toUart = 0.until(rx.availableForRead).map { rx.readByte().toUByte() }
             if (toUart.isNotEmpty()) Log.info("Sending to $device: $toUart")
 
+            var overflowCount = 0
+
             val fromUart = runOnMainThread {
                 if (stopOnHalt && processor.resetSwitch.enabled) {
                     throw RuntimeException("Processor stopped!")
                 }
                 for (byte in toUart) {
-                    uart.write(byte)
+                    if (!uart.write(byte)) overflowCount++
                 }
                 uart.readAll()
             }
 
+            if (overflowCount > 0) Log.warn("$device RX buffer is full, $overflowCount bytes dropped!")
+
             if (fromUart.isNotEmpty()) Log.info("Received from $device: $fromUart")
             for (byte in fromUart) {
                 tx.writeByte(byte.toByte())

mod/src/main/kotlin/gay/object/mlogv32/UartAccess.kt

@@ -6,8 +6,8 @@ import kotlin.reflect.KProperty
 class UartAccess(private val build: MemoryBuild, private val capacity: Int) {
     // NOTE: rx and tx refer to our receiver and transmitter, not the processor's
     private val txRptr by MemoryIntDelegate(build, 254)
-    private var txWptr by MemoryIntDelegate(build, 255)
-    private val txSize get() = (txWptr - txRptr).mod(capacity * 2)
+    private var txWptrRaw by MemoryIntDelegate(build, 255)
+    private val txWptr get() = txWptrRaw and 0xff
 
     private var rxRptr by MemoryIntDelegate(build, 510)
     private val rxWptr by MemoryIntDelegate(build, 511)
@@ -25,19 +25,29 @@ class UartAccess(private val build: MemoryBuild, private val capacity: Int) {
             return null
         }
 
-        val byte = build.memory[256 + rxRptr.mod(capacity)].toInt().toUByte()
-        rxRptr = (rxRptr + 1).mod(capacity * 2)
+        val byte = build.memory[256 + rxRptr].toInt().toUByte()
+        rxRptr = wrap(rxRptr + 1)
         return byte
     }
 
-    fun write(byte: UByte) {
-        if (txSize < capacity) {
-            build.memory[txWptr.mod(capacity)] = byte.toDouble()
-        }
-        if (txSize <= capacity) {
-            txWptr = (txWptr + 1).mod(capacity * 2)
+    fun write(byte: UByte, signalOverflow: Boolean = true): Boolean {
+        val nextWptr = wrap(txWptr + 1)
+
+        // full, maybe signal overflow
+        if (nextWptr == txRptr) {
+            if (signalOverflow) {
+                txWptrRaw = txWptr or 0x100
+            }
+            return false
         }
+
+        // not full, write a byte
+        build.memory[txWptr] = byte.toDouble()
+        txWptrRaw = nextWptr
+        return true
     }
+
+    private fun wrap(index: Int) = index.mod(capacity + 1)
 }
 
 class MemoryIntDelegate(

src/config/base.mlog.jinja

@@ -13,11 +13,12 @@
     set RAM_SIZE    {{#RAM_SIZE}}  # RAM size in bytes (rwx)
     set ICACHE_SIZE {{#ICACHE_SIZE}}  # icache size in variables, or bytes of memory it can represent; 4x less dense than ROM/RAM
 
-    set UART_FIFO_CAPACITY {{#UART_FIFO_CAPACITY}}  # UART TX/RX FIFO capacity in bytes (max 254)
+    set UART_FIFO_CAPACITY {{#UART_FIFO_CAPACITY}}  # UART TX/RX FIFO capacity in bytes (max 253)
 
     # computed values
-    op add MEMORY_X @thisx MEMORY_X_OFFSET
-    op add MEMORY_Y @thisy MEMORY_Y_OFFSET
+    op add MEMORY_X @thisx MEMORY_X_OFFSET  # absolute x position of bottom left memory proc
+    op add MEMORY_Y @thisy MEMORY_Y_OFFSET  # absolute y position of bottom left memory proc
+    op add UART_FIFO_MODULO UART_FIFO_CAPACITY 1  # actual number of indices used for each FIFO, keeping one empty to check if the buffer is full (max 254)
 
     stop
 
@@ -30,7 +31,7 @@ set MEMORY_WIDTH MEMORY_WIDTH
 set ROM_SIZE ROM_SIZE
 set RAM_SIZE RAM_SIZE
 set ICACHE_SIZE ICACHE_SIZE
-set UART_FIFO_CAPACITY UART_FIFO_CAPACITY
+set UART_FIFO_MODULO UART_FIFO_MODULO
 set MEMORY_X MEMORY_X
 set MEMORY_Y MEMORY_Y
 # {% endraw %}

src/config/configs.yaml

@@ -12,4 +12,4 @@ configs:
     ROM_SIZE: '0x480000'
     RAM_SIZE: '0x480000'
     ICACHE_SIZE: '0xc0000'
-    UART_FIFO_CAPACITY: 254
+    UART_FIFO_CAPACITY: 253

src/debugger.mlog.jinja

@@ -197,14 +197,16 @@ loop:
     read reservation_set CPU "reservation_set"
     read privilege_mode CPU "privilege_mode"
 
-    read UART_FIFO_CAPACITY CPU "UART_FIFO_CAPACITY"
-    op mul UART_FIFO_MODULO UART_FIFO_CAPACITY 2
+    read UART_FIFO_MODULO CPU "UART_FIFO_MODULO"
+    op sub UART_FIFO_CAPACITY UART_FIFO_MODULO 1
 
     read uart0_rx_rptr UART0 254
-    read uart0_rx_wptr UART0 255
+    read uart0_rx_wptr_raw UART0 255
     read uart0_tx_rptr UART0 510
     read uart0_tx_wptr UART0 511
 
+    op and uart0_rx_wptr uart0_rx_wptr_raw 0xff
+
     op sub uart0_rx_fifo_size uart0_rx_wptr uart0_rx_rptr
     op add uart0_rx_fifo_size uart0_rx_fifo_size UART_FIFO_MODULO
     op mod uart0_rx_fifo_size uart0_rx_fifo_size UART_FIFO_MODULO
@@ -213,11 +215,17 @@ loop:
     op add uart0_tx_fifo_size uart0_tx_fifo_size UART_FIFO_MODULO
     op mod uart0_tx_fifo_size uart0_tx_fifo_size UART_FIFO_MODULO
 
+    op equal uart0_rx_full uart0_rx_fifo_size UART_FIFO_CAPACITY
+    op notEqual uart0_rx_overflow_flag uart0_rx_wptr uart0_rx_wptr_raw
+    op land uart0_rx_overrun uart0_rx_full uart0_rx_overflow_flag
+
     read uart1_rx_rptr UART1 254
-    read uart1_rx_wptr UART1 255
+    read uart1_rx_wptr_raw UART1 255
     read uart1_tx_rptr UART1 510
     read uart1_tx_wptr UART1 511
 
+    op and uart1_rx_wptr uart1_rx_wptr_raw 0xff
+
     op sub uart1_rx_fifo_size uart1_rx_wptr uart1_rx_rptr
     op add uart1_rx_fifo_size uart1_rx_fifo_size UART_FIFO_MODULO
     op mod uart1_rx_fifo_size uart1_rx_fifo_size UART_FIFO_MODULO
@@ -226,6 +234,10 @@ loop:
     op add uart1_tx_fifo_size uart1_tx_fifo_size UART_FIFO_MODULO
     op mod uart1_tx_fifo_size uart1_tx_fifo_size UART_FIFO_MODULO
 
+    op equal uart1_rx_full uart1_rx_fifo_size UART_FIFO_CAPACITY
+    op notEqual uart1_rx_overflow_flag uart1_rx_wptr uart1_rx_wptr_raw
+    op land uart1_rx_overrun uart1_rx_full uart1_rx_overflow_flag
+
     # markers
 
     print "ROM_START\n{0}"
@@ -546,29 +558,33 @@ loop__no_mark_icache:
     format "machine"
 done_privilege_mode:
 
-    print "uart0_rx_fifo_size = {0}\n"
-    jump uart0_rx_fifo_size__no_overflow lessThanEq uart0_rx_fifo_size UART_FIFO_CAPACITY
-    format "{0} (!)"
-uart0_rx_fifo_size__no_overflow:
+    print "uart0_rx_size = {0} ({1} -> {2})"
+    jump uart0_rx_fifo_size__no_overrun notEqual uart0_rx_overrun true
+    print " !!"
+uart0_rx_fifo_size__no_overrun:
     format uart0_rx_fifo_size
+    format uart0_rx_rptr
+    format uart0_rx_wptr
+    print "\n"
 
-    print "uart0_tx_fifo_size = {0}\n\n"
-    jump uart0_tx_fifo_size__no_overflow lessThanEq uart0_tx_fifo_size UART_FIFO_CAPACITY
-    format "{0} (!)"
-uart0_tx_fifo_size__no_overflow:
+    print "uart0_tx_size = {0} ({1} -> {2})\n\n"
     format uart0_tx_fifo_size
+    format uart0_tx_rptr
+    format uart0_tx_wptr
 
-    print "uart1_rx_fifo_size = {0}\n"
-    jump uart1_rx_fifo_size__no_overflow lessThanEq uart1_rx_fifo_size UART_FIFO_CAPACITY
-    format "{0} (!)"
-uart1_rx_fifo_size__no_overflow:
+    print "uart1_rx_size = {0} ({1} -> {2})"
+    jump uart1_rx_fifo_size__no_overrun notEqual uart1_rx_overrun true
+    print " !!"
+uart1_rx_fifo_size__no_overrun:
     format uart1_rx_fifo_size
+    format uart1_rx_rptr
+    format uart1_rx_wptr
+    print "\n"
 
-    print "uart1_tx_fifo_size = {0}\n"
-    jump uart1_tx_fifo_size__no_overflow lessThanEq uart1_tx_fifo_size UART_FIFO_CAPACITY
-    format "{0} (!)"
-uart1_tx_fifo_size__no_overflow:
+    print "uart1_tx_size = {0} ({1} -> {2})\n"
     format uart1_tx_fifo_size
+    format uart1_tx_rptr
+    format uart1_tx_wptr
 
     #{{'\n'}} {{ print(36, 17) }}
 

src/init.mlog.jinja

@@ -1,11 +1,16 @@
 #% extends 'main.constants.jinja'
 #% block contents
 
-# this processor initializes INCR using a lookup table, sets readonly CSR values, and disables RAM procs to reduce lag
+# this processor performs the following one-time initialization steps:
+# - disable RAM procs to reduce lag
+# - initialize INCR using a lookup table
+# - set readonly CSR values
+# - reset all UART FIFO pointers to 0
+
 # the lookup table must be linked first
 
     set LOOKUP_START 0
-    set EXPECTED_LINKS 19
+    set EXPECTED_LINKS 21
 
     # wait until ready
 reset:
@@ -17,6 +22,8 @@ reset:
 
     set CSRS processor18
     set CPU processor19
+    set UART0 bank1
+    set UART1 bank2
 
     op div wait {{LOOKUP_PROC_SIZE}} 120 # micro proc instructions/sec
     op ceil wait wait
@@ -102,6 +109,16 @@ init_incr:
     write 0 CSRS "{{ 'mscratch'|csr }}"
     write 0 CSRS "{{ 'mie'|csr }}"
 
+    # init UARTs
+    write 0 UART0 {{UART_RX_RPTR}}
+    write 0 UART0 {{UART_RX_WPTR}}
+    write 0 UART0 {{UART_TX_RPTR}}
+    write 0 UART0 {{UART_TX_WPTR}}
+    write 0 UART1 {{UART_RX_RPTR}}
+    write 0 UART1 {{UART_RX_WPTR}}
+    write 0 UART1 {{UART_TX_RPTR}}
+    write 0 UART1 {{UART_TX_WPTR}}
+
     setrate 1
     stop
 
@@ -126,4 +143,8 @@ lookup_variable:
 set {{LOOKUP_PROC_SIZE}} null
 set {{ROM_PROC_BYTES}} null
 set {{RAM_PROC_VARS}} null
+set {{UART_RX_RPTR}} null
+set {{UART_RX_WPTR}} null
+set {{UART_TX_RPTR}} null
+set {{UART_TX_WPTR}} null
 # {% endraw %}

src/kbconv.mlog

@@ -6,9 +6,9 @@
 set COPYRIGHT "kbconv - a sortKB scancode decoder\n© 2025 camelStyleUser, BasedUser. Released under GPLv3 (https://www.gnu.org/licenses/gpl-3.0.html).\nThis program is provided without any warranty."
 set SOURCELINK "https://github.com/BasedUser/mPC"
 
-read UART_CAPACITY processor1 "UART_FIFO_CAPACITY"
-op mul UART_MODULO UART_CAPACITY 2
+read UART_FIFO_MODULO processor1 "UART_FIFO_MODULO"
 read uart_wptr bank1 255
+op and uart_wptr uart_wptr 0xff # clear overflow flag if set by another producer
 
 read modifiers cell2 0
 op and shift modifiers 1
@@ -59,22 +59,17 @@ jump handleSpecial greaterThan tgtmodifier 0  # but ONLY if there's anything to
 noApplySpecial: # TODO: once bank3 as scancode is in
 appliedSpecial:
 
-wait_for_uart:
-read uart_rptr bank1 254
-
-op sub uart_size uart_wptr uart_rptr
-op add uart_size uart_size UART_MODULO
-op mod uart_size uart_size UART_MODULO
+op add next_uart_wptr uart_wptr 1
+op mod next_uart_wptr next_uart_wptr UART_FIFO_MODULO
 
 # wait for uart to have space
-jump wait_for_uart greaterThanEq uart_size UART_CAPACITY
+wait_for_uart:
+read uart_rptr bank1 254
+jump wait_for_uart equal uart_rptr next_uart_wptr
 
 # uart has space, write a byte
-op mod i uart_wptr UART_CAPACITY
-write letter bank1 i
-
-op add uart_wptr uart_wptr 1
-op mod uart_wptr uart_wptr UART_MODULO
+write letter bank1 uart_wptr
+set uart_wptr next_uart_wptr
 write uart_wptr bank1 255
 jump loop always