From e37a2b1559570d567e35ae55928280b09b3655d1 Mon Sep 17 00:00:00 2001 From: sidney Date: Tue, 31 Dec 2024 13:35:16 +0100 Subject: [PATCH] Updated documentation with counter documentation. --- doc/sim65.sgml | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/doc/sim65.sgml b/doc/sim65.sgml index 962f07254..9c54c71f3 100644 --- a/doc/sim65.sgml +++ b/doc/sim65.sgml @@ -151,6 +151,71 @@ int main() // sim65 example.prg +Counter peripheral

+ +The sim65 simulator supports a memory-mapped counter peripheral that manages +a number of 64-bit counters that are continuously updated as the simulator is +running. For each counter, it also provides a 64 bit "latching" register. + +The functionality of the counter peripheral is accessible through 3 registers: + +* PERIPHERALS_COUNTER_LATCH ($FFC0, write-only) +* PERIPHERALS_COUNTER_SELECT ($FFC1, read/write) +* PERIPHERALS_COUNTER_VALUE ($FFC2..$FFC9, read-only) + +These three registers are used as follows. + +When a program explicitly requests a "counter latch" operation by writing any value +to the PERIPHERALS_COUNTER_LATCH address ($FFC0), all live registers are copied to +the latch registers. They will keep the latched value until another latch operation +updates them. + +The PERIPHERALS_COUNTER_SELECT address ($FFC1) register holds an 8-bit value that +specifies which 64-bit value is currently readable through the PERIPHERALS_COUNTER_VALUE +address range. Possible values are: + +$00: latched clock cycle counter selected. +$01: latched CPU instruction counter selected. +$02: latched IRQ interrupt counter selected. +$03: latched NMI interrupt counter selected. + +In addition to these counters, two other latch registers are available that are also +updated when the PERIPHERALS_COUNTER_LATCH address is written: + +$80: latched wallclock time (nanoseconds) selected. +$81: latched wallclock time (split s/ns) selected. + +When PERIPHERALS_COUNTER_LATCH equals $80, the PERIPHERALS_COUNTER_VALUE will be a +64-bit value corresponding to the number of nanoseconds elapsed since Midnight, Jan 1st, +1970 UTC. + +When PERIPHERALS_COUNTER_LATCH equals $81, the high 32 bits of PERIPHERALS_COUNTER_VALUE +will be a 32-bit value corresponding to the number of seconds elapsed since Midnight, +Jan 1st, 1970 UTC. The low 32 bits of PERIPHERALS_COUNTER_VALUE will hold the +nanoseconds since the start of that seconds. + +The two different wallclock-time latch registers are provided for different applications. +For some applications, the single 64-bit value will be more convenient, while for other +applications, the split 32/32 bits representations with separate seconds and nanoseconds +is more convenient. + +Note that the definition above given as "time since Midnight, Jan 1st, 1970 UTC" is an +approximation, as the implementation depends on the POSIX definition of time which does +not account for leap seconds. + +If the PERIPHERALS_COUNTER_SELECT register holds a value other than one of the six values +described above, all PERIPHERALS_COUNTER_VALUE bytes will read as zero. + +On reset, PERIPHERALS_COUNTER_SELECT is initialized to zero. + +The PERIPHERALS_COUNTER_VALUE addresses ($FFC2..$FFC9) are used to read to currently +selected latch register value. Address $FFF2 holds the least significant byte (LSB), +while address $FFC9 holds the most significant byte (MSB). + +On reset, all latch registers are reset to zero. this means that reading any of the +PERIPHERALS_COUNTER_VALUE bytes before a write to PERIPHERALS_COUNTER_LATCH will +yield zero. + Creating a Test in Assembly

Though a C test may also link with assembly code,