diff --git a/InstructionSets/README.md b/InstructionSets/README.md index fc50a84ea..a0c779083 100644 --- a/InstructionSets/README.md +++ b/InstructionSets/README.md @@ -1,8 +1,9 @@ -# Instruction Sets +# Instruction Sets Code in here provides the means to disassemble, and to execute code for certain instruction sets. It **does not seek to emulate specific processors** other than in terms of implementing their instruction sets. So: + * it doesn't involve itself in the actual bus signalling of real processors; and * instruction-level timing (e.g. total cycle counts) may be unimplemented, and is likely to be incomplete. @@ -13,6 +14,7 @@ This part of CLK is intended primarily to provide disassembly services for stati A decoder extracts fully-decoded instructions from a data stream for its associated architecture. The meaning of 'fully-decoded' is flexible but it means that a caller can easily discern at least: + * the operation in use; * its addressing mode; and * relevant registers. @@ -20,6 +22,7 @@ The meaning of 'fully-decoded' is flexible but it means that a caller can easily It may be assumed that callers will have access to the original data stream for immediate values, if it is sensible to do so. In deciding what to expose, what to store ahead of time and what to obtain just-in-time a decoder should have an eye on two principal consumers: + 1. disassemblers; and 2. instruction executors. @@ -50,6 +53,7 @@ A sample interface: std::pair decode(word_type *stream, size_t length) { ... } In this sample the returned pair provides an `int` size that is one of: + * a positive number, indicating a completed decoding that consumed that many `word_type`s; or * a negative number, indicating the [negatived] minimum number of `word_type`s that the caller should try to get hold of before calling `decode` again. @@ -58,6 +62,7 @@ A caller is permitted to react in any way it prefers to negative numbers; they'r ## Parsers A parser sits one level above a decoder; it is handed: + * a start address; * a closing bound; and * a target. @@ -65,6 +70,7 @@ A parser sits one level above a decoder; it is handed: It is responsible for parsing the instruction stream from the start address up to and not beyond the closing bound, and no further than any unconditional branches. It should post to the target: + * any instructions fully decoded; * any conditional branch destinations encountered; * any immediately-knowable accessed addresses; and @@ -75,6 +81,7 @@ So a parser has the same two primary potential recipients as a decoder: diassemb ## Executors An executor is responsible for only one thing: + * mapping from decoded instructions to objects that can perform those instructions. An executor is assumed to bundle all the things that go into instruction set execution: processor state and memory, alongside a parser. diff --git a/OSBindings/Mac/Clock SignalTests/68000 Comparative Tests/readme.md b/OSBindings/Mac/Clock SignalTests/68000 Comparative Tests/readme.md index 75d3e49be..e8155ad0c 100644 --- a/OSBindings/Mac/Clock SignalTests/68000 Comparative Tests/readme.md +++ b/OSBindings/Mac/Clock SignalTests/68000 Comparative Tests/readme.md @@ -3,12 +3,14 @@ Tests contained in this folder are original to Clock Signal. All are JSON. Tests assume a test machine consisting of a vanilla 68000 with 16mb of RAM. For each test either: + 1. start from a reset, e.g. if you have a prefetch queue you need to fill; or 2. just apply the entire initial state, which indicates the proper PC and A7 for itself. Then execute to the end of a single instruction (including any generated exception). Each file contains an array of dictionaries. Each dictionary is a single test and includes: + * a name; * initial memory contents; * initial register state; @@ -43,11 +45,13 @@ So the output is very scattergun approach, with a lot of redundancy. ## Known Issues Errors in generation mean that: + 1. MOVE is mostly untested; MOVEq is well-tested and other MOVEs appear within the test set as per the approximate generation algorithm above but due to an error in the generation of move.json, all of its opcodes are $2000 less than they should be, causing them to hit various instructions other than MOVE; 2. there is sparse coverage of the rotates and shifts: LS[L/R], AS[L/R], RO[L/R] and ROX[L/R]; and 3. there are similarly few tests of MULU. Issues with comparing results between multiple emulators in the case of unusual instructions mean that no tests have been generated for: + 1. MOVE [to or from] SR; 2. TRAP; 3. TRAPV; diff --git a/OSBindings/Mac/Clock SignalTests/AllSuiteA/readme.md b/OSBindings/Mac/Clock SignalTests/AllSuiteA/readme.md index 959121be8..fa93be7e5 100644 --- a/OSBindings/Mac/Clock SignalTests/AllSuiteA/readme.md +++ b/OSBindings/Mac/Clock SignalTests/AllSuiteA/readme.md @@ -1,2 +1,3 @@ # AllSuiteA Test Suite + This file was sourced from hmc-6502 — https://github.com/cminter/hmc-6502 — and was obtained with an unknown licence, believed to be BSD Simplified. \ No newline at end of file diff --git a/OSBindings/Mac/Clock SignalTests/Amiga Blitter Tests/README.md b/OSBindings/Mac/Clock SignalTests/Amiga Blitter Tests/README.md index 7f67d6fd7..1b3a13f5b 100644 --- a/OSBindings/Mac/Clock SignalTests/Amiga Blitter Tests/README.md +++ b/OSBindings/Mac/Clock SignalTests/Amiga Blitter Tests/README.md @@ -1,7 +1,8 @@ -## Amiga Blitter Tests +# Amiga Blitter Tests These tests record register writes and subsequent memory accesses by the Amiga Blitter over a variety of test cases. It is believed that they test all functionality other than stippled lines. They were generated using a slightly-inaccurate public domain model of the chip rather than from the real thing. In particular: + * these tests record the output as though the Blitter weren't pipelined — assuming all channels enabled, it always reads via A, then B, then C, then writes via D. The real Blitter performs two cycles of reads before its first write, and adds a final write with no additional reads; and * the tests do not record which pointer is used for a write target and therefore do not observe that the Blitter will use pointer C as a write destination for the first pixel of a line. diff --git a/OSBindings/Mac/Clock SignalTests/BCDTest/readme.md b/OSBindings/Mac/Clock SignalTests/BCDTest/readme.md index 881548c66..ebaceac92 100644 --- a/OSBindings/Mac/Clock SignalTests/BCDTest/readme.md +++ b/OSBindings/Mac/Clock SignalTests/BCDTest/readme.md @@ -1,2 +1,3 @@ # BCDTest + This test was obtained from http://stardot.org.uk/forums/viewtopic.php?t=8793#p97168 and is the work of David Banks, https://github.com/hoglet67 . It is believed to be public domain. \ No newline at end of file diff --git a/OSBindings/Mac/Clock SignalTests/Wolfgang Lorenz 6502 test suite/readme.md b/OSBindings/Mac/Clock SignalTests/Wolfgang Lorenz 6502 test suite/readme.md index d1e697f5c..ec1d0237a 100644 --- a/OSBindings/Mac/Clock SignalTests/Wolfgang Lorenz 6502 test suite/readme.md +++ b/OSBindings/Mac/Clock SignalTests/Wolfgang Lorenz 6502 test suite/readme.md @@ -1,2 +1,3 @@ # Wolfgang Lorenz’s Test Suite + The files in this folder were authored by Wolfgang Lorenz and were sourced as per http://www.softwolves.com/arkiv/cbm-hackers/7/7114.html ; they are believed to be public domain software. \ No newline at end of file diff --git a/Packaging/README.md b/Packaging/README.md index ee1a0e521..19b4b34c3 100644 --- a/Packaging/README.md +++ b/Packaging/README.md @@ -1,8 +1,9 @@ # RPM packaging for clksignal -This simple Ansible playbook creates and installs an RPM package of the current release of clksignal + +This simple Ansible playbook creates and installs an RPM package of the current release of clksignal. If the version that you build is newer than what you have installed, it will be automatically upgraded. ## Usage -`ansible-playbook main.yml -K + ansible-playbook main.yml -K diff --git a/README.md b/README.md index ec0209fe0..d4a650c5e 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,19 @@ ![Clock Signal Application Icon](READMEImages/Icon.png) + # Clock Signal + Clock Signal ('CLK') is an emulator that seeks to be invisible. Users directly launch classic software, avoiding the learning curves associated with emulators and with classic machines. macOS and source releases are [hosted on GitHub](https://github.com/TomHarte/CLK/releases). A Qt-based Linux build is available as a [Snap](https://snapcraft.io/clock-signal). This emulator seeks to offer: + * single-click load of any piece of source media for any supported platform; * with a heavy signal processing tilt for accurate reproduction of original outputs; * avoiding latency as much as possible. It currently contains emulations of the: + * Acorn Electron; * Amstrad CPC; * Apple II/II+ and IIe; @@ -26,6 +30,7 @@ It currently contains emulations of the: * Sinclair ZX Spectrum. Also present but very much upcoming are the: + * Commodore Amiga; and * early PC compatible.