moar

Author: rumbledethumps

docs/source/os.rst

@@ -9,10 +9,10 @@ Introduction
 ============
 
 The :doc:`ria` runs a 32-bit protected operating system that you can call
-from the 6502. The :doc:`os` does not use any 6502 system RAM and will not
+from the 6502. The OS does not use any 6502 system RAM and will not
 interfere with developing a native 6502 OS.
 
-The :doc:`os` loosely follows POSIX with an Application Binary
+The OS loosely follows POSIX with an Application Binary
 Interface (ABI) similar to `cc65's fastcall
 <https://cc65.github.io/doc/cc65-intern.html>`__. It provides stdio.h and
 unistd.h services to both `cc65 <https://cc65.github.io>`__ and `llvm-mos
@@ -58,7 +58,7 @@ Application Binary Interface
 
 The ABI for calling the operating system is based on fastcall from the
 `cc65 internals <https://cc65.github.io/doc/cc65-intern.html>`__. The
-:doc:`os` does not use or require anything from cc65 and is easy for
+OS does not use or require anything from cc65 and is easy for
 assembly programmers to use. At its core, the OS ABI is four simple rules.
 
 * Stack arguments are pushed left to right.
@@ -145,16 +145,16 @@ below as "A regs".
 Bulk Data
 ---------
 
-Functions that move bulk data may come in two flavors. These are any
-function with a mutable pointer parameter. A RAM pointer is meaningless to the RIA because it cannot change 6502
+Functions that move bulk data come in two flavors, depending on
+where the data lives. A RAM pointer is meaningless to the RIA because it cannot change 6502
 RAM. Instead, use the XSTACK or XRAM to move data.
 
 Bulk XSTACK Operations
 ~~~~~~~~~~~~~~~~~~~~~~
 
 These only work if the size is 512 bytes or less. Bulk data is passed on the
 XSTACK, which is 512 bytes. A pointer appears in the C prototype to indicate
-the type and direction of this data. Let's look at some examples.
+the type and direction (to or from the OS) of this data. Let's look at some examples.
 
 .. code-block:: C
 
@@ -200,7 +200,7 @@ going through 6502 RAM or capture a screenshot with ease.
    int write_xram(xram_addr buf, unsigned count, int fildes)
 
 The OS expects `buf` and `count` on the XSTACK as integers with `filedes` in
-RIA_A. The :doc:`os` has direct access to XRAM so internally it will use
+RIA_A. The OS has direct access to XRAM so internally it will use
 something like &XRAM[buf]. You will need to use RIA_RW0 or RIA_RW1 to access
 this memory from the 6502.
 
@@ -227,8 +227,8 @@ below has reordered arguments that are optimized for short stacking the long
 argument. But you don't have to call f_lseek() from C, you can call the
 usual lseek() which has the traditional argument order.
 
-The :doc:`os` is built around FAT filesystems, which is the defacto
-standard for unsecured USB storage devices. POSIX filesystems are not fully
+The OS is built around FAT filesystems, the de facto standard for
+unsecured USB storage devices. POSIX filesystems are not fully
 compatible with FAT but there is a solid intersection of basic IO that is
 100% compatible. You will see some familiar POSIX functions like open() and
 others like f_stat() which are similar to the POSIX function but tailored to
@@ -329,8 +329,8 @@ LRAND
 
    |
 
-   Generates a random number starting with entropy on the RIA. This is
-   suitable for seeding a RNG or general use. The 16-bit rand() in the cc65
+   Generates a 32-bit random number seeded with hardware entropy
+   from the RIA. Suitable for seeding a PRNG or direct use. The 16-bit rand() in the cc65
    library can be seeded with this by calling its non-standard _randomize()
    function.
 
@@ -351,8 +351,10 @@ STDIN_OPT
    buffer size - 1 to make gets() safe. This can also guarantee no split
    lines when using fgets() on STDIN.
 
-   *** Experimental *** Likely to be replaced with stty-like something. Drop
-   your thoughts on the forums if you have specific needs.
+   .. note::
+
+      **Experimental.** Likely to be replaced with a stty-like interface.
+      Share your thoughts on the forums if you have specific needs.
 
    :Op code: RIA_OP_STDIN_OPT 0x05
    :C proto: rp6502.h
@@ -374,13 +376,13 @@ ERRNO_OPT
 
    |
 
-   :doc:`os` calls will set RIA_ERRNO when an error occurs.  This is used to
+   OS calls will set RIA_ERRNO when an error occurs.  This is used to
    select which set of values to use because the compiler libraries each use
    different constants in errno.h. Both cc65 and llvm-mos call this
    automatically in the C runtime. The RIA_ERRNO behavior is undefined until
    it is set. Note that the C `errno` maps directly to RIA_ERRNO.
 
-   :doc:`os` will map FatFs errors onto errno. RP6502 emulation and
+   The OS will map FatFs errors onto errno. RP6502 emulation and
    simulation software is expected to map their native errors as well. The
    table below shows the FatFs mappings. Because FatFs is so integral to the
    OS, calls are documented here with their native FatFs errors to assist

docs/source/ria.rst

@@ -131,30 +131,35 @@ Registers
      - Write the OS operation id here to begin an OS call.
    * - $FFF0
      - IRQ
-     - Set bit 0 high to enable VSYNC interrupts. Verify source
-       with VSYNC increment then read or write this register to clear
-       interrupt.
+     - Set bit 0 high to enable VSYNC interrupts. To clear the
+       interrupt, first verify the source by checking the VSYNC
+       counter, then read or write this register.
    * - $FFF1
      - RETURN
-     - Always $80, BRA. Entry to blocking OS call.
+     - Always $80 (the BRA opcode). JSR here to spin-wait for an
+       OS call: the CPU loops on this BRA until BUSY clears, then
+       falls through to LDA and LDX below.
    * - $FFF2
      - BUSY
      - Bit 7 high while OS operation is running.
    * - $FFF3
      - LDA
-     - Always $A9.
+     - Always $A9 (the LDA immediate opcode). Part of the
+       spin-loop return sequence.
    * - $FFF4
      - A
      - OS call register A.
    * - $FFF5
      - LDX
-     - Always $A2.
+     - Always $A2 (the LDX immediate opcode). Part of the
+       spin-loop return sequence.
    * - $FFF6
      - X
      - OS call register X.
    * - $FFF7
      - RTS
-     - Always $60.
+     - Always $60 (the RTS opcode). Ends the spin-loop return
+       sequence, returning to the caller with A and X loaded.
    * - | $FFF8 -
        | $FFF9
      - SREG
@@ -190,10 +195,10 @@ portal would make moving XRAM very slow since data would have to
 buffer in 6502 RAM. Ideally, you won't move XRAM and can use the pair
 for better optimizations.
 
-STEP0 and STEP1 are reset to 1. These are signed so you can go
-backwards and reverse data. These adders allow for very fast sequential
-access, which typically makes up for the slightly slower random access
-compared to 6502 system RAM.
+STEP0 and STEP1 default to 1 after reset. Both are signed, so
+negative values traverse XRAM in reverse. These auto-increment
+adders enable very fast sequential access, which more than offsets
+the slightly slower random access compared to 6502 system RAM.
 
 Extended Stack (XSTACK)
 -----------------------
@@ -314,9 +319,10 @@ in XRAM.
   xreg_ria_keyboard(xaddr); // macro shortcut
 
 The RIA continuously updates XRAM with a bit array of USB HID
-keyboard codes. Note that these are not PS/2 scancodes.
-Each bit represents one key with the first four bits/codes having special
-meaning:
+keyboard keycodes. Note that these are not PS/2 scancodes.
+Each keycode is one bit in the array — bit N is 1 when the key
+with HID keycode N is currently pressed. The first four keycodes
+have special meaning:
 
 - 0 - No key pressed
 - 1 - Num Lock on
@@ -402,7 +408,7 @@ use a specific gamepad or include a "AB or BA" option.
    Retro-style gamepads are designed with button mappings for emulators while
    emulators expect the button layout of a modern gamepad. These do not cancel
    each other out. Instead, you end up with wonky button mappings that do not
-   follow the defacto standard for modern gamepads.
+   follow the de facto standard for modern gamepads.
 
 Enable and disable access to the RIA gamepad XRAM registers by setting
 the extended register. The register value is the XRAM start address of
@@ -513,9 +519,9 @@ with extended register device 0 channel 1 address 0x00.
 * Stereo panning.
 * PWM for all waveforms.
 
-Each of the eight oscillators requires eight bytes of XRAM for
-configuration. The unused byte is padding so multiplication is a fast
-bit shift.
+Each of the eight oscillators uses eight bytes of XRAM for
+configuration. The structure size is a power of two so indexing
+into the oscillator array is a bit shift rather than a multiply.
 
 .. code-block:: C
 
@@ -557,13 +563,13 @@ shenanigans.
      - 0-255 (0-100%) Duty cycle of oscillator. This affects all
        waveforms.
    * - vol_attack
-     - Attack volume and rate.
+     - Attack phase volume and rate.
 
        * bits 7-4 - 0-15 volume attenuation.
        * bits 3-0 - 0-15 attack rate.
 
    * - vol_decay
-     - Decay volume and rate.
+     - Decay phase volume and rate.
 
        * bits 7-4 - 0-15 volume attenuation.
        * bits 3-0 - 0-15 decay rate.
@@ -676,10 +682,10 @@ registers. The OPL2 registers must begin on a page boundary.
 If, for example, xaddr is 0x4200 then the 256 registers of an OPL2 chip
 are mapped into XRAM from 0x4200 to 0x42FF.
 
-Timers, interrupts, and the status register are not supported and were
-not widely used. These were in Yamaha OPL chips to assist with cost
-reducing consumer devices and rarely used in computers which had their
-own timers.
+Timers, interrupts, and the status register are not supported.
+These features existed in Yamaha OPL chips primarily to help
+cost-reduce consumer devices; computers of the era had their own
+timers and rarely used them.
 
 
 Virtual Communications Port
@@ -740,7 +746,8 @@ and ``len`` bytes of raw binary data:
    * - Field
      - Description
    * - ``addr``
-     - Destination address in 6502 RAM or XRAM.
+     - Destination address in 6502 RAM (0x0000-0xFEFF) or XRAM
+       (0x10000-0x1FFFF).
    * - ``len``
      - Number of raw binary bytes that immediately follow this line.
    * - ``crc``

docs/source/ria_w.rst

@@ -9,7 +9,7 @@ Introduction
 ============
 
 The **RP6502 Interface Adapter W** is a Raspberry Pi Pico 2 W running
-the RP6502-RIA-W firmware. The :doc:`ria_w` provides all the features
+the RP6502-RIA-W firmware. It provides all the features
 of the :doc:`ria` plus wireless services, as described below.
 
 
@@ -44,7 +44,7 @@ Network Time Protocol (NTP)
 ===========================
 
 The real-time clock (RTC) automatically synchronizes with internet time
-servers when connected. Check NTP status with the ``status`` command.
+servers when connected to WiFi. Check NTP status with the ``status`` command.
 
 - **Set Time Zone:**
   To use local time instead of UTC, set your time zone with ``SET TZ``.
@@ -57,7 +57,7 @@ Once WiFi and time zone are configured, timekeeping is automatic.
 Modem Emulation
 ===============
 
-The :doc:`ria_w` can emulate a Hayes modem for BBS access. Raw TCP and
+The RP6502-RIA-W can emulate a Hayes modem for BBS access. Raw TCP and
 telnet connections are unencrypted in transit.
 
 - **AT Commands:**
@@ -81,7 +81,7 @@ Example AT commands:
 - ``AT&V`` — View profile
 - ``AT&W`` — Write profile to NVRAM
 - ``AT&Z0=example.com:23`` — Save "telephone number" to NVRAM
-- ``AT+RF=your_ssid`` and ``AT+RF?`` — Access RIA setting RF
+- ``AT+RF=0`` or ``AT+RF=1`` and ``AT+RF?`` — Access RIA setting RF
 - ``AT+RFCC=your_ssid`` and ``AT+RFCC?`` — Access RIA setting RFCC
 - ``AT+SSID=your_ssid`` and ``AT+SSID?`` — Access RIA setting SSID
 - ``AT+PASS=your_pass`` and ``AT+PASS?`` — Access RIA setting PASS
@@ -96,7 +96,7 @@ profiles.
 Bluetooth
 =========
 
-The :doc:`ria_w` supports Bluetooth LE (BLE) keyboards, mice, and
+The RP6502-RIA-W supports Bluetooth LE (BLE) keyboards, mice, and
 gamepads. Bluetooth Classic (BR/EDR) is not supported.
 BLE has been widely available since Bluetooth 4.0 (June 2010),
 so compatible devices are easy to find, though the occasional oddball

docs/source/vga.rst

@@ -8,7 +8,7 @@ Introduction
 =============
 
 The RP6502 Video Graphics Array is a Raspberry Pi Pico 2 with
-:doc:`vga` firmware. Its primary data connection is to a :doc:`ria`
+RP6502-VGA firmware. Its primary data connection is to a :doc:`ria`
 over a 5-wire PIX bus. More than one VGA module can be put on a PIX
 bus. Note that all VGA modules share the same 64K of XRAM and only
 the first one will generate frame numbers and vsync interrupts.
@@ -46,8 +46,10 @@ ANSI palette of 16 colors, followed by 216 colors (6x6x6), followed
 by 24 greys.
 
 16-bit colors are built with the following bit logic. Setting the
-alpha bit will make the color opaque. The built-in ANSI color
-palette has the alpha bit set on all colors except color 0 black.
+alpha bit makes the color opaque; clearing it makes the color
+transparent. Despite the name, this is a binary flag, not a
+blending factor. The built-in ANSI color palette has the alpha bit
+set on all colors except color 0 (black), which is transparent.
 
 .. code-block:: C