links and bullets

Author: rumbledethumps

docs/source/hardware.rst

@@ -41,11 +41,11 @@ Step 0. Read This
 
 Rev. A and Rev. B circuit boards are identical except for the debug
 connectors under the RIA. These do nothing even when connected. They were
-removed so folks stop asking about them.
+removed so folks would stop asking about them.
 
 Most VGA-to-HDMI cables can get power from the Picocomputer. Some will need
 external power applied. All are zero lag. All VGA video output uses only
-HDMI-compatible timings so these cables are an ideal solution.
+HDMI-compatible timings, so these cables are an ideal solution.
 
 The boot message does not say COLOR anymore. Do not assume your device will
 behave exactly the same as an old YouTube video.
@@ -81,7 +81,7 @@ for production in multiples of five. You won't be able to order only one board.
 
 There are a ton of options you can change if you like. The defaults will get
 you a classic green and white board with lead (Pb) HASL. Consider getting the
-lead-free HASL upgrade if the other four boards will be kicking around a drawer
+lead-free HASL upgrade if the other four boards will be kicking around in a drawer
 for the next 20 years.
 
 
@@ -106,7 +106,7 @@ Expect a short delay while they quote the bill of materials. Then pay
 and wait. They estimated four weeks; mine arrived in three.
 
 If they have a question, make sure both you and your sales rep read the notes
-you sent them. If you have a question about options on their web site, ask your
+you sent them. If you have a question about options on their website, ask your
 sales rep before asking on the forums. They help people all day long with
 projects far more complex than this. Even if you don't understand what you are
 doing, they can figure it out by looking at the zip files. Really, they do this
@@ -127,7 +127,7 @@ Mouser will print the Customer# on each of the parts bags. Assign this
 column to the CSV reference column to get your bags labelled like "C1-C9, C11"
 etc. If you forget, no problem because the PCB silkscreen has location info.
 
-If something is out of stock, consult the substitution notes below.
+If something is out of stock, consult the `Parts Substitution`_ notes below.
 
 
 Step 5. Pi Pico Firmware

docs/source/index.rst

@@ -35,28 +35,33 @@ Community
 Specs
 =====
 
-- **CPU** — WDC 65C02 CPU and WDC 65C22 VIA
+- **Core** — WDC 65C02 CPU and WDC 65C22 VIA; variable 0.1-8.0 MHz
 - **RAM** — 64 KB system + 64 KB extended
+- **ROM** — 1 MB of onboard flash for installing and auto-booting ROMs
 - **Video** — VGA and HD output; 3 planes, scanline programmable
-- **Sound** — PSG and OPL2 FM
+- **Sound** — PSG (8 voices) and OPL2 FM (9 voices)
 - **Clock** — Real-Time Clock with DST
+- **TRNG** — True random number generator
 
 
 Connectivity
 ============
 
-- **USB** — keyboard, mouse, gamepads, UART serial, NFC, floppy drives, and flash drives
-- **Bluetooth LE** — keyboard, mouse, and gamepads
 - **WiFi** — NTP time sync, Hayes modem emulation for dialing into BBSs
+- **Bluetooth LE** — keyboard, mouse, and gamepads
+- **USB Host** — keyboard, mouse, gamepads, hubs, UART serial, NFC, floppy drives, and flash drives
+- **USB Device** — driverless CDC ACM; mirrors the VGA ANSI terminal console
 
 
 Programming
 ===========
 
 - **Protected OS** — 32-bit operating system; uses no 6502 RAM
-- **POSIX-compatible API** — stdio.h and unistd.h for cc65 and llvm-mos
 - **FAT filesystem** — read and write files on any USB flash or floppy drive
-- **ROM flash** — 1 MB of onboard flash for installing and auto-booting ROMs
+- **POSIX-compatible API** — stdio.h and unistd.h for cc65 and llvm-mos
+- **cc65** — `VS Code integration for cc65 <https://github.com/picocomputer/vscode-cc65>`__
+- **llvm-mos** — `VS Code integration for llvm-mos <https://github.com/picocomputer/vscode-llvm-mos>`__
+- **AI Assistance** — The latest models via VS Code extensions or GitHub Copilot
 
 
 Build It

docs/source/os.rst

@@ -122,15 +122,15 @@ is only updated if there is an error.
 
 Some operations return strings or structures on the stack. You must pull the
 entire stack before the next call. However, tail call optimizations are
-possible. For example, you can chain ``read_xstack()`` and ``write_xstack()`` to
+possible. For example, you can chain `read_xstack() <READ_XSTACK_>`_ and `write_xstack() <WRITE_XSTACK_>`_ to
 copy a file without using any RAM or XRAM.
 
 Short Stacking
 ---------------
 
 In the pursuit of saving every cycle, you can save a few on the stack
 push when you don't need the full range. This only applies to the first
-stack argument pushed. For example:
+stack argument pushed. For example, in `LSEEK`_:
 
 .. code-block:: C
 
@@ -168,7 +168,7 @@ the type and direction (to or from the OS) of this data. Let's look at some exam
    int open(const char *path, int oflag);
 
 Send ``oflag`` in ``RIA_A``. ``RIA_X`` doesn't need to be set according to the
-docs below. Send the path on XSTACK by pushing the string starting with the last
+`OPEN`_ docs. Send the path on XSTACK by pushing the string starting with the last
 character. You may omit pushing the terminating zero, but strings are
 limited to a length of 255. Calling this from the C SDK will "just work"
 because there's an implementation that pushes the string for you.
@@ -178,7 +178,7 @@ because there's an implementation that pushes the string for you.
    int read_xstack(void *buf, unsigned count, int fildes)
 
 Send ``count`` as a short stack and ``fildes`` in ``RIA_A``. ``RIA_X`` doesn't
-need to be set according to the docs below. The returned value in AX indicates how
+need to be set according to the `READ_XSTACK`_ docs. The returned value in AX indicates how
 many values must be pulled from the stack. If you call this from the C SDK
 then it will copy XSTACK to buf[] for you.
 
@@ -187,7 +187,7 @@ then it will copy XSTACK to buf[] for you.
    int write_xstack(const void *buf, unsigned count, int fildes)
 
 Send ``fildes`` in ``RIA_A``. ``RIA_X`` doesn't need to be set according to the
-docs below. Push the buf data to XSTACK. Do not send ``count``, the OS knows this
+`WRITE_XSTACK`_ docs. Push the buf data to XSTACK. Do not send ``count``, the OS knows this
 from its internal stack pointer. If you call this from the C SDK then it
 will copy count bytes of buf[] to XSTACK for you.
 
@@ -198,7 +198,7 @@ implementation makes multiple OS calls as necessary.
 Bulk XRAM Operations
 ~~~~~~~~~~~~~~~~~~~~
 
-These load and save XRAM directly. You can load game assets without
+These load and save XRAM directly via `READ_XRAM`_ and `WRITE_XRAM`_. You can load game assets without
 going through 6502 RAM or capture a screenshot with ease.
 
 .. code-block:: C
@@ -554,7 +554,7 @@ READ
 
 
    Read `count` bytes from a file to a buffer. This is implemented in the
-   compiler library as a series of calls to read_xstack().
+   compiler library as a series of calls to `READ_XSTACK`_.
 
    :Op code: None
    :C proto: unistd.h
@@ -614,7 +614,7 @@ WRITE
 
 
    Write `count` bytes from buffer to a file. This is implemented in the
-   compiler library as a series of calls to write_xstack().
+   compiler library as a series of calls to `WRITE_XSTACK`_.
 
    :Op code: None
    :C proto: unistd.h
@@ -1169,7 +1169,7 @@ get-only attribute also returns -1 with ``EINVAL``.
    * - | 0x02
        | ``RIA_ATTR_CODE_PAGE``
      - Active OEM code page used by the filesystem, console, and default
-       VGA font. Reverts to the system setting when the 6502 stops. If the
+       :doc:`VGA <vga>` font. Reverts to the system setting when the 6502 stops. If the
        requested page is unavailable, the console setting is selected;
        follow a set with a get to confirm the result.
        One of: 437, 720, 737, 771, 775, 850, 852, 855, 857, 860, 861, 862,

docs/source/ria.rst

@@ -59,7 +59,7 @@ crashed or halted 6502, you have two options:
 1. Using a Bluetooth or USB keyboard, press CTRL-ALT-DEL.
 2. Send a break to the RIA UART.
 
-.. warning::
+.. caution::
 
    Do not hook up a physical button to RESB. The RIA must remain
    in control of RESB. What you probably want is the reset that happens
@@ -95,31 +95,31 @@ Registers
      - Read bytes from the UART.
    * - $FFE3
      - VSYNC
-     - Increments every 1/60 second when PIX VGA device 1 is
+     - Increments every 1/60 second when :doc:`PIX VGA <vga>` device 1 is
        connected.
    * - $FFE4
      - RW0
-     - Read or write the XRAM referenced by ADDR0.
+     - Read or write the `Extended RAM (XRAM)`_ referenced by ADDR0.
    * - $FFE5
      - STEP0
      - Signed byte added to ADDR0 after every access to RW0.
    * - | $FFE6 -
        | $FFE7
      - ADDR0
-     - Address of XRAM for RW0.
+     - Address of `Extended RAM (XRAM)`_ for RW0.
    * - $FFE8
      - RW1
-     - Read or write the XRAM referenced by ADDR1.
+     - Read or write the `Extended RAM (XRAM)`_ referenced by ADDR1.
    * - $FFE9
      - STEP1
      - Signed byte added to ADDR1 after every access to RW1.
    * - | $FFEA -
        | $FFEB
      - ADDR1
-     - Address of XRAM for RW1.
+     - Address of `Extended RAM (XRAM)`_ for RW1.
    * - $FFEC
      - XSTACK
-     - 512 bytes for OS call stack.
+     - 512 bytes for `Extended Stack (XSTACK)`_.
    * - $FFED
      - ERRNO_LO
      - Low byte of errno. All errors fit in this byte.
@@ -128,7 +128,7 @@ Registers
      - Ensures errno is optionally a 16-bit int.
    * - $FFEF
      - OP
-     - Write the OS operation id here to begin an OS call.
+     - Write the :doc:`OS <os>` operation id here to begin an OS call.
    * - $FFF0
      - IRQ
      - Set bit 0 high to enable VSYNC interrupts. To clear the
@@ -222,16 +222,16 @@ and device 0 on the PIX bus.
     - Description
   * - $0:0:00
     - KEYBOARD
-    - See Keyboard section
+    - See `Keyboard`_ section
   * - $0:0:01
     - MOUSE
-    - See Mouse section
+    - See `Mouse`_ section
   * - $0:0:02
     - GAMEPADS
-    - See Gamepads section
+    - See `Gamepads`_ section
   * - $0:1:00
     - PSG
-    - See Programmable Sound Generator section
+    - See `Programmable Sound Generator`_ section
 
 
 Pico Information Exchange (PIX)
@@ -399,7 +399,7 @@ Square/Triangle/Cross/Circle and XY/AB layouts are "the official" layout
 of the RP6502. You can, of course, do your own thing and request players
 use a specific gamepad or include a "AB or BA" option.
 
-.. attention::
+.. note::
    **The RP6502 expects modern gamepads.**
 
    The RP6502 is not an emulation platform. Sega, NES, SNES, TG16, Atari,

docs/source/ria_w.rst

@@ -49,7 +49,8 @@ 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``.
   Use ``HELP SET TZ`` for guidance. Daylight saving adjustments are
-  automatic if your locale observes them.
+  automatic if your locale observes them. The :doc:`os` provides
+  programmatic access to the clock and time zone.
 
 Once WiFi and time zone are configured, timekeeping is automatic.
 

docs/source/vga.rst

@@ -68,7 +68,8 @@ ignore the palette. Palettes must be 16-bit aligned.
   } palette[2^bits_per_pixel];
 
 
-Programming the VGA device is done with PIX extended registers -
+Programming the VGA device is done with `PIX extended registers
+<ria.html#pix-extended-registers-xreg>`__ -
 XREGS. VGA is PIX device ID 1. Registers are 16 bit values addressed
 by $device:$channel:register. e.g. $1:0:0F
 
@@ -112,11 +113,11 @@ Setting key registers may return a failure (-1) with errno EINVAL.
       $1:0:02-$1:0:FF cleared after programming. Each mode has a
       section of this document for its own registers.
 
-      * 0 - Console
-      * 1 - Character
-      * 2 - Tile
-      * 3 - Bitmap
-      * 4 - Sprite
+      * 0 - `Console <#mode-0-console>`__
+      * 1 - `Character <#mode-1-character>`__
+      * 2 - `Tile <#mode-2-tile>`__
+      * 3 - `Bitmap <#mode-3-bitmap>`__
+      * 4 - `Sprite <#mode-4-sprite>`__
 
 
 Mode 0: Console
@@ -507,7 +508,8 @@ that set them.
 
   * - $1:F:01
     - CODE_PAGE
-    - Set code page for built-in font.
+    - Set code page for built-in font. Matches
+      `RIA_ATTR_CODE_PAGE <os.html#ria-attributes>`__.
   * - $1:F:02
     - UART
     - Set bit rate. Reserved, not implemented.
@@ -548,7 +550,7 @@ When bit 0x80 is set, the 0x70 bits indicate the command type, and the
 0x0F bits are a scalar for the command.
 
 0x80 VSYNC - The scalar will increment and be used for the LSB of the
-RIA_VSYNC register.
+`RIA VSYNC <ria.html#registers>`__ register.
 
 0x90 OP_ACK - Some XREG locations are triggers for remote calls which
 may fail or take time to complete. This acknowledges a successful