The big cycle unit rework (#534)

* Fix ambiguity in clock units

The M-cycle crusade!

* Fix missing terminator

* Fix typos and missed spelling errors

* Correct and convert "Timer Global Circuit" to SVG

Fixes #492 by moving the DIV-APU bits from 5 and 6 to 4 and 5.
Also applies the "TODO: correct the diagram" note.

Also tries to reorganise the diagram and reword some bits to be
more consistent with the rest of the document, and improve clarity.

* Correctly reflect which bits don't exist on the diagram

* Provide fallback values for viewing the SVG stand-alone

* Convert DIV+TAC diagrams to "themed" SVGs

Also restore the CGB version of that diagram

* Tweak presentation of "system counter" a little

---------

Co-authored-by: Eldred HABERT <[email protected]>

Author: SonoSooS

src/CGB_Registers.md

@@ -168,7 +168,7 @@ would be recommended to use Single Speed whenever possible.
 
 In Double Speed Mode the following will operate twice as fast as normal:
 
-- The CPU (2.10 MHz, so 1 cycle = approx. 0.5 µs)
+- The CPU (2.10 MHz, so 1 M-cycle = approx. 0.5 µs)
 - Timer and Divider Registers
 - Serial Port (Link Cable)
 - DMA Transfer to OAM
@@ -179,7 +179,7 @@ And the following will keep operating as usual:
 - HDMA Transfer to VRAM
 - All Sound Timings and Frequencies
 
-The CPU stops for 2050 cycles (= 8200 clocks) after the `stop` instruction is
+The CPU stops for 2050 M-cycles (= 8200 T-cycles) after the `stop` instruction is
 executed. During this time, the CPU is in a strange state. `DIV` does not tick, so
 *some* audio events are not processed. Additionally, VRAM/OAM/... locking is "frozen", yielding
 different results depending on the [PPU mode](<#PPU modes>) it's started in:

src/Gameboy_Camera.md

@@ -187,7 +187,7 @@ This means that the GB Camera shouldn't be used in GBC double speed mode!
 :::
 
 The time needed to capture and process an image depends on the exposure time and the value of N bit of the register 1 of the M64282FP chip.
-In GAME BOY CYCLES (1 MiHz):
+In Game Boy M-cycles (1 MiHz):
 
 ```
 N_bit    = ([A001] & BIT(7)) ? 0 : 512
@@ -200,7 +200,7 @@ Divide those values by 2 to get the sensor clocks.
 ### Capture process timings
 
 The next values are in sensor clocks.
-Multiply by 2 to get Game Boy cycles:
+Multiply by 2 to get Game Boy M-cycles:
 
 ```
     - Reset pulse.

src/MBC3.md

@@ -93,4 +93,4 @@ Year-10000-Proof, provided that the cartridge gets used at least every
 ### Delays
 
 When accessing the RTC Registers, it is recommended to wait 4 µs
-(4 cycles in Normal Speed Mode) between any separate accesses.
+(4 M-cycles in Single Speed Mode) between any separate accesses.

src/MBC5.md

@@ -5,7 +5,7 @@ It can map up to 64 Mbits (8 MiB) of ROM.
 MBC5 (Memory Bank Controller 5) is the 4th generation MBC. There
 apparently was no MBC4, presumably because of the superstition about the
 number 4 in Japanese culture. It is the first MBC that is guaranteed to
-work properly with GBC double speed mode.
+work properly with GBC Double Speed mode.
 
 ## Memory
 

src/OAM_Corruption_Bug.md

@@ -47,7 +47,7 @@ The following operations are affected by this bug:
 - `push rr`, the `call` family, `rst xx` and interrupt handling -
   Pushing to the stack will trigger the bug 4 times; two usual writes
   and two glitched writes caused by the implied `dec sp`. However, since one
-  glitched write occurs in the same cycle as a actual write, this will
+  glitched write occurs in the same M-cycle as a actual write, this will
   effectively behave like 3 writes.
 - Executing code from OAM - If PC is inside OAM (reading $FF,
   that is, `rst $38`) the bug will trigger twice, once for increasing PC

src/OAM_DMA_Transfer.md

@@ -12,7 +12,7 @@ Source:      $XX00-$XX9F   ;XX = $00 to $DF
 Destination: $FE00-$FE9F
 ```
 
-The transfer takes 160 machine cycles: 640 dots (1.4 lines) in normal speed,
+The transfer takes 160 M-cycles: 640 dots (1.4 lines) in normal speed,
 or 320 dots (0.7 lines) in CGB Double Speed Mode.
 This is much faster than a CPU-driven copy.
 
@@ -64,15 +64,15 @@ Many games copy a routine like it into HRAM and call it during Mode 1.
 run_dma:
     ld a, HIGH(start address)
     ldh [$FF46], a  ; start DMA transfer (starts right after instruction)
-    ld a, 40        ; delay for a total of 4×40 = 160 cycles
+    ld a, 40        ; delay for a total of 4×40 = 160 M-cycles
 .wait
-    dec a           ; 1 cycle
-    jr nz, .wait    ; 3 cycles
+    dec a           ; 1 M-cycle
+    jr nz, .wait    ; 3 M-cycles
     ret
 ```
 
 If HRAM is tight, this more compact procedure saves 5 bytes of HRAM
-at the cost of a few cycles spent jumping to the tail in HRAM.
+at the cost of a few M-cycles spent jumping to the tail in HRAM.
 
 ```rgbasm
 run_dma:          ; This part must be in ROM.
@@ -86,8 +86,8 @@ run_dma_tail:     ; This part must be in HRAM.
 .wait
     dec b
     jr nz, .wait
-    ret z         ; Conditional `ret` is 1 cycle slower, which avoids
-                  ; reading from the stack on the last cycle of DMA.
+    ret z         ; Conditional `ret` is 1 M-cycle slower, which avoids
+                  ; reading from the stack on the last M-cycle of DMA.
 ```
 
 If starting a mid-frame transfer, wait for Mode 0 first

src/Rendering.md

@@ -9,7 +9,7 @@ The main implication of this rendering process is the existence of **raster effe
 The most famous raster effect is modifying the [scrolling registers](<#LCD Position and Scrolling>) between scanlines to create a ["wavy" effect](https://gbdev.io/guides/deadcscroll#effects).
 
 A "**dot**" = one 2<sup>22</sup> Hz (≅ 4.194 MHz) time unit.
-Dots remain the same regardless of whether the CPU is in [double speed](<#FF4D — KEY1 (CGB Mode only): Prepare speed switch>), so there are 4 dots per single-speed CPU cycle, and 2 per double-speed CPU cycle.
+Dots remain the same regardless of whether the CPU is in [Double Speed mode](<#FF4D — KEY1 (CGB Mode only): Prepare speed switch>), so there are 4 dots per Single Speed M-cycle, and 2 per Double Speed M-cycle.
 
 :::tip NOTE
 
@@ -64,10 +64,10 @@ Only the OBJ's leftmost pixel matters here, transparent or not; it is designated
    3. Incur this many dots of penalty, or zero if negative (from waiting for the BG fetch to finish).
 3. Incur a flat, 6-dot penalty (from fetching the OBJ's tile).
 
-**Exception**: an OBJ with an OAM X position of 0 (thus, completely off the left side of the screen) always incurs a 11-cycle penalty, regardless of `SCX`.
+**Exception**: an OBJ with an OAM X position of 0 (thus, completely off the left side of the screen) always incurs a 11-dot penalty, regardless of `SCX`.
 
 
-[^first12]: The 12 extra cycles come from two tile fetches at the beginning of Mode 3. One is the first tile in the scanline (the one that gets shifted by `SCX` % 8 pixels), the other is simply discarded.
+[^first12]: The 12 extra dots of penalty come from two tile fetches at the beginning of Mode 3. One is the first tile in the scanline (the one that gets shifted by `SCX` % 8 pixels), the other is simply discarded.
 
 [^crt]: The Game Boy can afford to "take pauses", because it writes to a LCD it fully controls; by contrast, home consoles like the NES or SNES are on a schedule imposed by the screen they are hooked up to. Taking pauses arguably simplified the PPU's design while allowing greater flexibility to game developers.
 

src/STAT.md

@@ -2,7 +2,7 @@
 
 :::tip TERMINOLOGY
 
-A *dot* is the shortest period over which the PPU can output one pixel: is it equivalent to 1 T-state on DMG or on CGB single-speed mode or 2 T-states on CGB double-speed mode. On each dot during mode 3, either the PPU outputs a pixel or the fetcher is stalling the [FIFOs](<#Pixel FIFO>).
+A *dot* is the shortest period over which the PPU can output one pixel: is it equivalent to 1 T-cycle on DMG or on CGB Single Speed mode or 2 T-cycles on CGB Double Speed mode. On each dot during mode 3, either the PPU outputs a pixel or the fetcher is stalling the [FIFOs](<#Pixel FIFO>).
 
 :::
 
@@ -36,7 +36,7 @@ is set, and (if enabled) a STAT interrupt is requested.
 A hardware quirk in the monochrome Game Boy makes the LCD interrupt
 sometimes trigger when writing to STAT (including writing \$00) during
 OAM scan, HBlank, VBlank, or LY=LYC. It behaves as if \$FF were
-written for one cycle, and then the written value were written the next
-cycle. Because the GBC in DMG mode does not have this quirk, two games
+written for one M-cycle, and then the written value were written the next
+M-cycle. Because the GBC in DMG mode does not have this quirk, two games
 that depend on this quirk (Ocean's *Road Rash* and Vic Tokai's *Xerd
 no Densetsu*) will not run on a GBC.

src/Timer_Obscure_Behaviour.md

@@ -1,41 +1,63 @@
 # Timer obscure behaviour
 
+:::tip System counter
+
+DIV is just the visible part of the **system counter**.
+
+The **system counter** is constantly incrementing every M-cycle, unless the CPU is in [STOP mode](<#Using the STOP Instruction>).
+
+:::
+
 ## Timer Global Circuit
 
-![](imgs/timer_simplified.svg "imgs/timer_simplified.svg")
+{{#include imgs/src/timer_simplified.svg:2:}}
 
 ## Relation between Timer and Divider register
 
 This is a schematic of the circuit involving TAC and DIV:
 
-![](imgs/timer_tac_bug_dmg.svg "imgs/timer_tac_bug_dmg.svg")
+<figure><figcaption>
+
+On **DMG**:
+
+</figcaption>
+{{#include imgs/src/timer_tac_bug_dmg.svg:2:}}
+</figure>
+
+<figure><figcaption>
+
+On **CGB**:
+
+</figcaption>
+{{#include imgs/src/timer_tac_bug_gbc.svg:2:}}
+</figure>
 
 Notice how the values that are connected to the inputs of the
 multiplexer are the values of those bits, not the carry of those bits.
 This is the reason of a few things:
 
-- When writing to DIV, the whole counter is reset, so the timer is
+- When writing to DIV, the system counter is reset to zero, so the timer is
 also affected.
 
 - When writing to DIV, if the current output is 1 and timer is
-enabled, as the new value after reseting DIV will be 0, the falling
+enabled, as the new value after reseting the system counter will be 0, the falling
 edge detector will detect a falling edge and TIMA will increase.
 
 - When writing to TAC, if the previously selected multiplexer input was
-1 and the new input is 0, TIMA will increase too. This doesnt
+1 and the new input is 0, TIMA will increase too. This doesn't
 happen when the timer is disabled, but it also happens when disabling
-the timer (the same effect as writing to DIV). The following code explains the behaviour in DMG and MGB.
+the timer (the same effect as writing to DIV). The following code explains the behavior in DMG and MGB.
 
 ```
-    clocks_array[4] = {1024, 16, 64, 256}
+    clocks_array[4] = {256, 4, 16, 64}
 
     old_clocks = clocks_array[old_TAC&3]
     new_clocks = clocks_array[new_TAC&3]
 
     old_enable = old_TAC & BIT(2)
     new_enable = new_TAC & BIT(2)
 
-    sys_clocks = 16 bit system counter
+    sys_clocks = system counter
 
     IF old_enable == 0 THEN
         glitch = 0 (*)
@@ -50,24 +72,23 @@ the timer (the same effect as writing to DIV). The following code explains the b
 
 The sentence marked with a (\*) has a different behaviour in GBC (AGB
 and AGS seem to have strange behaviour even in the other statements).
-When enabling the timer and maintaining the same frequency it doesnt
-glitch. When disabling the timer it doesnt glitch either. When another
+When enabling the timer and maintaining the same frequency it doesn't
+glitch. When disabling the timer it doesn't glitch either. When another
 change of value happens (so timer is enabled after the write), the
 behaviour depends on a race condition, so it cannot be predicted for
 every device.
 
 ## Timer Overflow Behaviour
 
 When TIMA overflows, the value from TMA is loaded and IF timer flag is
-set to 1, but this doesnt happen immediately. Timer interrupt is
-delayed 1 cycle (4 clocks) from the TIMA overflow. The TMA reload to
-TIMA is also delayed. For one cycle, after overflowing TIMA, the value
+set to 1, but this doesn't happen immediately. Timer interrupt is
+delayed 1 M-cycle from the TIMA overflow. The TMA reload to
+TIMA is also delayed. For 1 M-cycle, after overflowing TIMA, the value
 in TIMA is $00, not TMA. This happens only when an overflow happens, not
-when the upper bit goes from 1 to 0, it cant be done manually writing
+when the upper bit goes from 1 to 0, it can't be done manually writing
 to TIMA, the timer has to increment itself.
 
-For example (SYS is the system internal counter divided by 4 for easier
-understanding, each increment of the graph is 1 cycle, not 1 clock):
+For example (SYS here is the lower 8 bits of the system counter):
 
     Timer overflows:
 
@@ -88,14 +109,14 @@ understanding, each increment of the graph is 1 cycle, not 1 clock):
 - During the strange cycle \[A\] you can prevent the IF flag from being
 set and prevent the TIMA from being reloaded from TMA by writing a value
 to TIMA. That new value will be the one that stays in the TIMA register
-after the instruction. Writing to DIV, TAC or other registers wont
+after the instruction. Writing to DIV, TAC or other registers won't
 prevent the IF flag from being set or TIMA from being reloaded.
 
-- If you write to TIMA during the cycle that TMA is being loaded to it
+- If you write to TIMA during the M-cycle that TMA is being loaded to it
 \[B\], the write will be ignored and TMA value will be written to TIMA
 instead.
 
-- If TMA is written the same cycle it is loaded to TIMA \[B\], TIMA is
+- If TMA is written the same M-cycle it is loaded to TIMA \[B\], TIMA is
 also loaded with that value.
 
 - This is a guessed schematic to explain the priorities with registers
@@ -105,5 +126,5 @@ TIMA and TMA:
 
 TMA is a latch. As soon as it is written, the output shows that value.
 That explains that when TMA is written and TIMA is being incremented,
-the value written to TMA is also written to TIMA. It doesnt affect the
-IF flag, though.
+the value written to TMA is also written to TIMA. It doesn't affect the
+IF flag though.

src/Timer_and_Divider_Registers.md

@@ -36,7 +36,7 @@ TAC (because every increment is an overflow). However, if TMA is set to $FE, an
 only requested every two increments, which effectively divides the selected clock by two. Setting
 TMA to $FD would divide the clock by three, and so on.
 
-If a TMA write is executed on the same cycle as the content of TMA is transferred to TIMA
+If a TMA write is executed on the same M-cycle as the content of TMA is transferred to TIMA
 due to a timer overflow, the old value is transferred to TIMA.
 
 ## FF07 — TAC: Timer control
@@ -51,13 +51,13 @@ due to a timer overflow, the old value is transferred to TIMA.
 
   <div class="table-wrapper"><table>
     <thead>
-      <tr><th rowspan=2>Clock select</th><th rowspan=2>Base clock</th><th colspan=3>Frequency (Hz)</th></tr>
+      <tr><th rowspan=2>Clock select</th><th rowspan=2>Increment every</th><th colspan=3>Frequency (Hz)</th></tr>
       <tr><th>DMG, SGB2, CGB in single-speed mode</th><th>SGB1</th><th>CGB in double-speed mode</th></tr>
     </thead><tbody>
-      <tr><td>00</td><td>CPU Clock / 1024</td><td>  4096</td><td>  ~4194</td><td>  8192</td></tr>
-      <tr><td>01</td><td>CPU Clock / 16  </td><td>262144</td><td>~268400</td><td>524288</td></tr>
-      <tr><td>10</td><td>CPU Clock / 64  </td><td> 65536</td><td> ~67110</td><td>131072</td></tr>
-      <tr><td>11</td><td>CPU Clock / 256 </td><td> 16384</td><td> ~16780</td><td> 32768</td></tr>
+      <tr><td>00</td><td>256 M-cycles </td><td>  4096</td><td>  ~4194</td><td>  8192</td></tr>
+      <tr><td>01</td><td>4 M-cycles   </td><td>262144</td><td>~268400</td><td>524288</td></tr>
+      <tr><td>10</td><td>16 M-cycles  </td><td> 65536</td><td> ~67110</td><td>131072</td></tr>
+      <tr><td>11</td><td>64 M-cycles  </td><td> 16384</td><td> ~16780</td><td> 32768</td></tr>
     </tbody>
   </table></div>