clock_gettimezone updated

Author: rumbledethumps

.gitignore

@@ -1 +1,2 @@
 /docs/build
+/venv/

.vscode/settings.json

@@ -1,5 +1,8 @@
 {
-    "esbonio.sphinx.buildDir" : "${workspaceFolder}/docs/build",
-    "esbonio.sphinx.confDir"  : "${workspaceFolder}/docs/source",
-    "esbonio.sphinx.srcDir"   : "${workspaceFolder}/docs/source",
+    "esbonio.sphinx.buildDir": "${workspaceFolder}/docs/build",
+    "esbonio.sphinx.confDir": "${workspaceFolder}/docs/source",
+    "esbonio.sphinx.srcDir": "${workspaceFolder}/docs/source",
+    "restructuredtext.linter.doc8.extraArgs": [
+        "--ignore D001"
+    ],
 }

docs/source/api.rst

@@ -79,7 +79,7 @@ Functions that move bulk data may come in two flavors. These are any function wi
 2.3.1. Bulk XSTACK Operations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-These only work if the count is 256 or less. Bulk data is passed on the XSTACK, which is 256 bytes. A pointer appears in the C prototype to indicate the type and direction of this data. Let's look at some examples.
+These only work if the count is 512 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.
 
 .. code-block:: C
 
@@ -131,9 +131,9 @@ xreg
 
 .. c:function:: int xregn(char device, char channel, unsigned char address, unsigned count, ...);
 
-   Use xreg() with cc65 and xregn() with LLVM-MOS. The only difference is that xregn() requires a count of the variadic arguments.
+   The only difference is that xregn() requires a count of the variadic arguments. Using xreg() avoids making a counting error and is slightly smaller in CC65.
 
-   Set extended registers on a PIX device. See the :doc:`ria` and :doc:`vga` documentation for what each register does. Setting extended registers can fail, which you should use for feature detection. EINVAL means the device responded with a negative acknowledgementg. EIO means there was a timeout waiting for ack/nak.
+   Set extended registers on a PIX device. See the :doc:`ria` and :doc:`vga` documentation for what each register does. Setting extended registers can fail, which you should use for feature detection. EINVAL means the device responded with a negative acknowledgement. EIO means there was a timeout waiting for ack/nak.
 
    :param device: PIX device ID. 0-6
    :param channel: PIX channel. 0-15
@@ -149,7 +149,7 @@ phi2
 
    Retrieves the PHI2 setting from the RIA. Applications can use this for adjusting to or rejecting different clock speeds.
 
-   :returns: The 6502 clock speed in kHz. 500 <= x <= 8000
+   :returns: The 6502 clock speed in kHz. Typically 750 <= x <= 8000.
    :errno: will not fail
 
 
@@ -205,6 +205,13 @@ clock_getres
 
 .. c:function:: int clock_getres(clockid_t clock_id, struct timespec *res)
 
+   .. code-block:: c
+
+      struct timespec {
+         uint32_t tv_sec; /* seconds */
+         int32_t tv_nsec; /* nanoseconds */
+      };
+
    Copies the clock resolution to `res`.
 
    :param clock_id: 0 for CLOCK_REALTIME.
@@ -242,14 +249,25 @@ clock_settime
 clock_gettimezone
 -----------------
 
-.. c:function:: int clock_gettimezone(clockid_t clock_id, struct _timezone *tz)
+.. c:function:: int clock_gettimezone(uint32_t time, clockid_t clock_id, struct _timezone *tz)
+
+   .. code-block:: c
 
-   Not implemented. Always fails.
+      struct _timezone
+      {
+         int8_t daylight;  /* >0 if daylight savings time active */
+         int32_t timezone; /* Number of seconds behind UTC */
+         char tzname[5];   /* Name of timezone, e.g. CET */
+         char dstname[5];  /* Name when daylight true, e.g. CEST */
+      };
 
+   Populates a CC65 _timezone structure for the requested time. Use `help set tz` on the monitor to learn about configuring your time zone.
+
+   :param time: time_t compatible integer.
    :param clock_id: 0 for CLOCK_REALTIME.
-   :returns: -1 always.
+   :returns: 0 on success. -1 on error.
    :a regs: return, clock_id
-   :errno: ENOSYS
+   :errno: EINVAL
 
 
 open

docs/source/hardware.rst

@@ -6,22 +6,47 @@ Schematic
 
 `Picocomputer 6502 <_static/2023-06-07-rp6502.pdf>`_ (pdf)
 
-I use "Picocomputer 6502" to refer to the reference design. Please use a differentiating name if you change the hardware. For example, "Picocomputer VERA" or "Ulf's Dream Computer". Think about what people asking for help should call the device and go with that.
+
+Memory Map
+----------
+
+There is no ROM. Nothing in zero page is used or reserved. There isn't a book-sized list to study. The Picocomputer design lets you start with a clean slate for every project. VGA, USB, and WiFi are all accessed using the 32 registers of the RIA.
+
+.. list-table::
+   :widths: 25 75
+   :header-rows: 1
+
+   * - Address
+     - Description
+   * - 0000-FEFF
+     - RAM, 63.75K
+   * - FF00-FFCF
+     - Unassigned
+   * - FFD0-FFDF
+     - VIA, see the `WDC datasheet <https://www.westerndesigncenter.com/wdc/w65c22-chip.php>`_
+   * - FFE0-FFFF
+     - RIA, see the :doc:`RP6502 datasheet <ria>`
+   * - 10000-1FFFF
+     - RAM, 64K for :doc:`RIA <ria>` and :doc:`VGA <vga>`
+
+The unassigned space is available for hardware experimenters. You will need to redesign the address decoder logic hardware to use this address space. It is recommended that additional VIAs be added "down" and other hardware added "up". For example: VIA0 at FFD0, VIA1 at FFC0, SID0 at FF00, and SID1 at FF20.
+
+I use "Picocomputer 6502" to refer to the reference design with the above memory map. Please use a differentiating name if you change the hardware. For example, "Picocomputer VERA" or "Ulf's Dream Computer". Think about what people asking for help should call the device and go with that.
 
 Buying a Picocomputer
 ---------------------
 
 You will need to place two orders. First, for the Printed Circuit Board. Second, for the electronic components. Some PCB factories will do the soldering for you, but you'll still need to order the ICs and plug them into sockets.
 
-I have circuit boards in a `Tindie store <https://www.tindie.com/stores/rumbledethumps/>`_ that ships to the United States. International shipping is either too slow or too much when compared to getting boards made locally or in China.
+I have circuit boards in a `Tindie store <https://www.tindie.com/stores/rumbledethumps/>`_ that ships only to the United States. International shipping is either too slow or too expensive when compared to getting boards made locally or in China.
+
+USA import tariffs are not an issue with this project. Only a few dollars of resistors are made in China. Orders to my store and Mouser ship from the USA so you won't get a surprise bill from the courier.
 
 Step 0. Read This
 =================
 
 The boot message does not say COLOR anymore. Do not assume your device will behave exactly the same as an old YouTube video.
 
-USB hub and device support isn't perfect but everyone so far has been able to find working devices. Sometimes swapping hub ports helps.
-
 The three-pin debug connections under the RIA aren't used anymore. This is an artifact of early development.
 
 Most VGA-to-HDMI cables can get power from the Picocomputer. Some will need external power applied. All are zero lag.
@@ -75,7 +100,7 @@ Step 5. Pi Pico Firmware
 
 Download the `UF2 files  <https://github.com/picocomputer/rp6502/releases>`_.
 
-To load firmware on a Pi Pico, hold its BOOTSEL button down while plugging it into a computer. The Pi Pico will appear as a storage device. Copy the VGA UF2 file to make a Pico VGA and the RIA UF2 file to make a Pico RIA. It should take less than 15 seconds to copy. The LED turns on when done.
+To load firmware on a Pi Pico, hold its BOOTSEL button down while plugging it into a computer. The Pi Pico will appear as a storage device. Copy the VGA UF2 file to make a Pico VGA and the RIA UF2 file to make a Pico RIA. It should take less than 30 seconds to copy. The LED turns on when done.
 
 Acrylic Sandwich Case
 ---------------------
@@ -132,4 +157,4 @@ The RAM IC is 128k because 2x32k is more expensive. Speed must be \<=70ns for 8M
 
 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 has been tested. Both original and "H" (header) versions work great. Pin-compatible alternatives may work, check the forums. The 3-pin SWD connection on the Pi Pico RIA is no longer used internally and may be ignored when looking for alternatives.
+Only the Raspberry Pi design of the Pi Pico has been tested. Both original and "H" (header) versions work great. Pin-compatible alternatives may 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.