Pure 6502.

Author: rumbledethumps

docs/source/hardware.rst

@@ -81,8 +81,8 @@ 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 in a drawer
-for the next 20 years.
+lead-free HASL upgrade if the other four boards will be kicking around in a
+drawer for the next 20 years.
 
 
 Step 3. Order Assembly
@@ -131,15 +131,15 @@ If something is out of stock, consult the `Parts Substitution`_ notes below.
 
 
 Step 5. Pi Pico Firmware
-=========================
+========================
 
 Download the `UF2 files
 <https://github.com/picocomputer/rp6502/releases>`_.
 
 To load firmware on a Pi Pico 2, hold its BOOTSEL button down while plugging it
-into a computer. The Pi Pico 2 will appear as a storage device. Copy the RIA UF2
-file to make a :doc:`ria_w` and the VGA UF2 file to make a :doc:`vga`. It should
-take less than 30 seconds to copy. The LED turns on when done.
+into a computer. The Pi Pico 2 will appear as a storage device. Copy the RIA W
+UF2 file to make a :doc:`ria_w` and the VGA UF2 file to make a :doc:`vga`. It
+should take less than 30 seconds to copy. The LED turns on when done.
 
 
 Acrylic Sandwich Case
@@ -152,7 +152,7 @@ top and 3.5 mm for the bottom.
 
 
 Full Parts List (All Components)
-=================================
+================================
 
 `All Parts CSV <_static/rp6502-revb-full.csv>`_
 
@@ -162,7 +162,7 @@ Full Parts List (All Components)
 
 
 Active Parts List (ICs Only)
-=============================
+============================
 
 `Active Parts CSV <_static/rp6502-revb-active.csv>`_
 
@@ -182,7 +182,7 @@ Alternative part numbers for the Pi Picos.
 
 
 Parts Substitution
-===================
+==================
 
 All resistors are <= 1% tolerance. Any power rating. Leads must fit 0.8mm
 plated holes spaced 10mm apart. Recommended size is approximately 0.1" x 0.25"
@@ -220,7 +220,7 @@ The WDC W65C02S and W65C22S must not be substituted. Do not attempt to use
 NMOS chips (without the C in the number). Some older CMOS designs may work but
 there are no plans to support out-of-production ICs.
 
-Only the Raspberry Pi design of the Pi Pico 2 has been tested. Both original and
-"H" (header) versions work great. Pin-compatible alternatives usually work, check
-the forums. The 3-pin SWD connection on the Pi Pico RIA is no longer used and
-may be ignored when looking for alternatives.
+Only the Raspberry Pi design of the Pi Pico 2 has been tested. Both original
+and "H" (header) versions work great. Pin-compatible alternatives usually work,
+check the forums. The 3-pin SWD connection on the Pi Pico RIA is no longer
+used and may be ignored when looking for alternatives.

docs/source/index.rst

@@ -11,10 +11,10 @@
 Picocomputer 6502
 ==================
 
-All the soul of the 6502. None of the compromises. You're welcome.
+Pure 6502. No governor. No speed limits.
 
 The **Picocomputer 6502** is an open source, modern-retro gaming computer
-built around a real WDC 65C02. The design philosophy: keep the essence of
+built around a real WDC 65C02. The design philosophy: keep the soul of
 programming a 6502 and 6522, then rethink everything else.
 
 .. image:: _static/ria-w-sandwich.jpg
@@ -40,25 +40,33 @@ Specs
 - **ROM** — 1 MB of onboard flash for installing and auto-booting ROMs
 - **Video** — VGA and HD output; 3 planes, scanline programmable
 - **Sound** — PSG (8 voices) and OPL2 FM (9 voices)
-- **Clock** — Real-Time Clock with DST
+- **Clock** — Real-Time Clock with Daylight Savings Time
 - **TRNG** — True random number generator
 
 
+Quality of Life
+===============
+- **Open by Design** — DIY-friendly with fully open source hardware and software
+- **Storage** — Blazing fast 512 KB/sec USB flash drive reads and writes
+- **Keyboard** — International keyboard layout support
+- **Fonts** — Built-in code pages for international character sets
+
+
 Connectivity
 ============
 
 - **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
+- **USB Device** — driverless CDC ACM; console access (can operate headless)
 
 
 Programming
 ===========
 
 - **Protected OS** — 32-bit operating system; uses no 6502 RAM
 - **FAT filesystem** — read and write files on any USB flash or floppy drive
-- **POSIX-compatible API** — stdio.h and unistd.h for cc65 and llvm-mos
+- **API** — POSIX-like C library for familiar, portable programming
 - **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

docs/source/os.rst

@@ -80,17 +80,19 @@ as a C declaration like so:
 
 .. c:function:: int doit(int arg0, int arg1);
 
-The RIA has registers called ``RIA_A``, ``RIA_X``, and ``RIA_SREG``. An int is 16 bits,
-so we set the ``RIA_A`` and ``RIA_X`` registers with arg1. I'll use "A" for the 6502
-register and "RIA_A" for the RIA register in this explanation.
+The RIA has registers called ``RIA_A``, ``RIA_X``, and ``RIA_SREG``. An int
+is 16 bits, so we set the ``RIA_A`` and ``RIA_X`` registers with arg1. I'll
+use "A" for the 6502 register and "RIA_A" for the RIA register in this
+explanation.
 
 We use the XSTACK for arg0. Reading ``RIA_XSTACK`` pops bytes; writing
 pushes bytes. It's a top-down stack, so push each argument left to
 right and maintain little-endian byte order.
 
-To execute the call, store the operation ID in ``RIA_OP``. The operation begins
-immediately. You can keep doing 6502 things, like running a loading animation, by
-polling ``RIA_BUSY``. Alternatively, JSR to ``RIA_SPIN`` to block.
+To execute the call, store the operation ID in ``RIA_OP``. The operation
+begins immediately. You can keep doing 6502 things, like running a loading
+animation, by polling ``RIA_BUSY``. Alternatively, JSR to ``RIA_SPIN`` to
+block.
 
 ``JSR RIA_SPIN`` can unblock within 3 clock cycles and immediately loads A
 and X. Sequential operations run fastest with this technique. Under the hood,
@@ -116,13 +118,14 @@ flag N. Once clear, we read ``RIA_A`` and ``RIA_X`` with absolute instructions.
    LDA RIA_A
    LDX RIA_X
 
-All operations returning ``RIA_A`` will also return ``RIA_X`` to assist with C
-integer promotion. ``RIA_SREG`` is only updated for 32-bit returns. ``RIA_ERRNO``
-is only updated if there is an error.
+All operations returning ``RIA_A`` will also return ``RIA_X`` to assist with
+C integer promotion. ``RIA_SREG`` is only updated for 32-bit returns.
+``RIA_ERRNO`` 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() <READ_XSTACK_>`_ and `write_xstack() <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
@@ -153,23 +156,24 @@ Bulk Data
 ---------
 
 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.
+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 (to or from the OS) 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
 
    int open(const char *path, int oflag);
 
 Send ``oflag`` in ``RIA_A``. ``RIA_X`` doesn't need to be set according to the
-`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
+`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,18 +182,18 @@ 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 `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.
+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.
 
 .. code-block:: C
 
    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
-`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.
+`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.
 
 Note that read() and write() are part of the C SDK, not an OS operation. C
 requires these to support a count larger than the XSTACK can return so the
@@ -198,26 +202,26 @@ implementation makes multiple OS calls as necessary.
 Bulk XRAM Operations
 ~~~~~~~~~~~~~~~~~~~~
 
-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.
+These load and save XRAM directly via `READ_XRAM`_ and `WRITE_XRAM`_. You can
+directly load assets without going through 6502 RAM.
 
 .. code-block:: C
 
    int read_xram(xram_addr buf, unsigned count, int fildes)
    int write_xram(xram_addr buf, unsigned count, int fildes)
 
-The OS expects ``buf`` and ``count`` on the XSTACK as integers with ``fildes`` in
-``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.
+The OS expects ``buf`` and ``count`` on the XSTACK as integers with
+``fildes`` in ``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.
 
 These operations stand out for their high performance and ability to
 run in the background while the 6502 does other work. Expect close to
-64 KB/sec, meaning a game level's worth of assets loads in under a
-second.
+512 KB/sec, meaning a full 64KB of XRAM can load or save in under 150ms.
 
-Bulk XRAM operations are why the Picocomputer 6502 was designed without
-paged memory.
+Bulk XRAM operations are why the Picocomputer 6502 doesn't have paged memory.
+It's not necessary when "disk" access has no seek time and can move data as
+fast or faster then the CPU.
 
 
 Application Programmer Interface
@@ -243,10 +247,10 @@ 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
-FAT. Should it ever become necessary to have a POSIX ``stat()``, it can be
-implemented in the C standard library or in an application by translating
-``f_stat()`` data.
+others like ``f_stat()`` which are similar to the POSIX function but
+tailored to FAT. Should it ever become necessary to have a POSIX ``stat()``,
+it can be implemented in the C standard library or in an application by
+translating ``f_stat()`` data.
 
 ZXSTACK
 -------
@@ -299,14 +303,16 @@ ARGV
 .. c:function:: int _argv (char *argv, int size)
 
 
-   The virtual _argv is called by C initialization to provide argc and argv for main().
-   It returns an array of zero terminated string indexes followed by the strings.
+   The virtual _argv is called by C initialization to provide argc and
+   argv for main(). It returns an array of zero terminated string indexes
+   followed by the strings.
    e.g. ["ABC", "DEF"] is 06 00 0A 00 00 00 41 42 43 00 44 45 46 00
    The returned data is guaranteed to be valid.
 
-   Because this can use up to 512 bytes of RAM you must opt-in by providing storage
-   for the argv data. You may use static memory, or dynamically allocated memory which
-   can be freed after use. You may also reject an oversized argv by returning NULL.
+   Because this can use up to 512 bytes of RAM you must opt-in by
+   providing storage for the argv data. You may use static memory, or
+   dynamically allocated memory which can be freed after use. You may also
+   reject an oversized argv by returning NULL.
 
    .. code-block:: c
 
@@ -332,12 +338,14 @@ EXEC
 
    The data sent by _exec() will be checked for pointer safety and sanity, but
    will assume the path points to a loadable ROM file. If EINVAL is returned,
-   the argv buffer is cleared so further attempts to _argv() will return an empty set.
-   If the ROM is invalid, the user will be left on the console with an error message.
+   the argv buffer is cleared so further attempts to _argv() will return an
+   empty set. If the ROM is invalid, the user will be left on the console
+   with an error message.
 
    :Op code: RIA_OP_EXEC 0x09
    :C proto: rp6502.h
-   :returns: Does not return on success — the new ROM begins executing. -1 on error.
+   :returns: Does not return on success — the new ROM begins
+      executing. -1 on error.
    :errno: EINVAL
 
 
@@ -430,8 +438,9 @@ TZSET
          char dstname[5];  /* Name when daylight true, e.g. CEST */
       };
 
-   The virtual _tzset() is called internally by tzset(). Use `help set tz` on the
-   console monitor to learn about configuring your time zone.
+   The virtual _tzset() is called internally by tzset(). Use
+   `help set tz` on the console monitor to learn about configuring your
+   time zone.
 
    :Op code: RIA_OP_TZSET 0x0D
    :C proto: time.h
@@ -784,8 +793,8 @@ STAT
          char fname[255 + 1];
       } f_stat_t;
 
-   Returns file or directory info for requested path.
-   See the `FatFs documentation <https://elm-chan.org/fsw/ff/doc/sfileinfo.html>`__
+   Returns file or directory info for requested path. See the
+   `FatFs documentation <https://elm-chan.org/fsw/ff/doc/sfileinfo.html>`__
    for details about the data structure.
 
    :Op code: RIA_OP_STAT 0x1F
@@ -825,8 +834,8 @@ READDIR
 .. c:function:: int f_readdir (f_stat_t* dirent, int dirdes)
 
 
-   Returns directory entry info for the current read position of a directory descriptor,
-   then advances the read position.
+   Returns directory entry info for the current read position of a
+   directory descriptor, then advances the read position.
 
    :Op code: RIA_OP_READDIR 0x21
    :C proto: rp6502.h
@@ -1162,8 +1171,8 @@ ROM Cartridge Menu
 
 The most straightforward use of the launcher is a menu-driven ROM selector,
 analogous to inserting a physical cartridge into a retro console. The launcher
-ROM scans the storage device for ``.rp6502`` files, presents a list to the user,
-and calls `EXEC`_ with the chosen filename. When that ROM stops — whether
+ROM scans the storage device for ``.rp6502`` files, presents a list to the
+user, and calls `EXEC`_ with the chosen filename. When that ROM stops — whether
 normally or due to an error — the process manager automatically re-executes the
 launcher, returning the user to the selection menu.
 
@@ -1187,9 +1196,9 @@ OS cannot alter the launcher ROM; OS launchers are meant to stay simple and
 trustworthy. This indirection provides important capabilities:
 
 * **Fault recovery** — If the OS kernel encounters a fatal error it cannot
-  handle internally, it calls `EXIT`_ rather than locking up. The process manager
-  re-executes the launcher, which can choose to relaunch the kernel or take
-  some other action.
+  handle internally, it calls `EXIT`_ rather than locking up. The process
+  manager re-executes the launcher, which can choose to relaunch the kernel
+  or take some other action.
 
 * **Self-update** — An OS can prepare its own ROM update and call `EXIT`_. The
   launcher detects the pending update, applies it, and boots the new OS ROM —
@@ -1224,9 +1233,9 @@ get-only attribute also returns -1 with ``EINVAL``.
    * - | 0x02
        | ``RIA_ATTR_CODE_PAGE``
      - Active OEM code page used by the filesystem, console, and default
-       :doc:`VGA <vga>` font. Reverts to the system setting when the ROM stops. If the
-       requested page is unavailable, the system setting is selected;
-       follow a set with a get to confirm the result.
+       :doc:`VGA <vga>` font. Reverts to the system setting when the ROM
+       stops. If the requested page is unavailable, the system 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,
        863, 864, 865, 866, 869, 932, 936, 949, 950.
    * - | 0x03