skoolkit 10.0__cp314-cp314-win_amd64.whl

skoolkit/__init__.py

@@ -0,0 +1,239 @@
+# © 2011-2026 Richard Dymond (rjdymond@gmail.com)
+#
+# This file is part of SkoolKit.
+#
+# SkoolKit is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# SkoolKit is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# SkoolKit. If not, see <http://www.gnu.org/licenses/>.
+
+import argparse
+import html
+import sys
+import os
+import posixpath
+import textwrap
+import importlib
+
+try:
+    from skoolkit.csimulator import CSimulator
+except ImportError: # pragma: C no cover
+    CSimulator = None
+
+try:
+    from skoolkit.ccmiosimulator import CCMIOSimulator
+except ImportError: # pragma: C no cover
+    CCMIOSimulator = None
+
+VERSION = '10.0'
+PACKAGE_DIR = os.path.dirname(__file__)
+
+BASE_10 = 10
+BASE_16 = 16
+
+CASE_LOWER = 1
+CASE_UPPER = 2
+
+WRAPPER = textwrap.TextWrapper(break_long_words=False, break_on_hyphens=False)
+
+AE_CHARS = frozenset(' !=+-*/<>&|^%$ABCDEFabcdef0123456789()')
+
+ROM48 = os.path.join(PACKAGE_DIR, 'resources', '48.rom')
+
+ROM128 = (
+    os.path.join(PACKAGE_DIR, 'resources', '128-0.rom'),
+    os.path.join(PACKAGE_DIR, 'resources', '128-1.rom')
+)
+
+ROM_PLUS2 = (
+    os.path.join(PACKAGE_DIR, 'resources', 'plus2-0.rom'),
+    os.path.join(PACKAGE_DIR, 'resources', 'plus2-1.rom')
+)
+
+def error(msg):
+    sys.stderr.write('ERROR: {0}\n'.format(msg))
+    sys.exit(1)
+
+def warn(msg):
+    sys.stderr.write('WARNING: {0}\n'.format(msg))
+
+def info(msg):
+    sys.stderr.write('{0}\n'.format(msg))
+
+def show_package_dir():
+    write_line(PACKAGE_DIR)
+    sys.exit(0)
+
+def write(text):
+    sys.stdout.write(text)
+    sys.stdout.flush()
+
+def write_line(text):
+    sys.stdout.write('{0}\n'.format(text))
+
+def write_text(text):
+    sys.stdout.write(text)
+
+def wrap(text, width):
+    WRAPPER.width = width
+    return WRAPPER.wrap(text)
+
+def get_int_param(num_str, accept0x=False):
+    try:
+        return int(num_str)
+    except ValueError:
+        pass
+    if num_str.startswith('$'):
+        return int(num_str[1:], 16)
+    if accept0x and num_str.startswith('0x'):
+        return int(num_str[2:], 16)
+    if num_str.startswith('%'):
+        return int(num_str[1:], 2)
+    if num_str.startswith('"') and num_str.endswith('"'):
+        try:
+            if num_str.startswith('"\\'):
+                return ord(num_str[2:-1])
+            return ord(num_str[1:-1])
+        except TypeError:
+            pass
+    raise ValueError
+
+def parse_int(num_str, default=None):
+    try:
+        return get_int_param(num_str)
+    except ValueError:
+        return default
+
+def evaluate(param, safe=False):
+    try:
+        return get_int_param(param)
+    except ValueError:
+        pass
+    param = html.unescape(param)
+    if safe or set(param) <= AE_CHARS:
+        try:
+            return int(eval(param.replace('$', '0x').replace('/', '//').replace('&&', ' and ').replace('||', ' or ')))
+        except:
+            pass
+    raise ValueError
+
+def get_address_format(hexadecimal=False, lower=False):
+    if hexadecimal:
+        if lower:
+            return '${:04x}'
+        return '${:04X}'
+    return '{:05d}'
+
+def get_object(name_spec, default_path=''):
+    path, sep, name = name_spec.rpartition(':')
+    if sep:
+        sys.path.insert(0, os.path.expanduser(path) or default_path)
+    try:
+        return importlib.import_module(name)
+    except ImportError:
+        pass
+    mod_name, sep, attr_name = name.rpartition('.')
+    try:
+        m = importlib.import_module(mod_name or attr_name)
+    except ImportError as e:
+        raise SkoolKitError("Failed to import object {}: {}".format(name, e.args[0]))
+    try:
+        return getattr(m, attr_name)
+    except AttributeError:
+        raise SkoolKitError("No object named '{}' in module '{}'".format(attr_name, mod_name))
+
+def find_file(fname, search_dirs=('',)):
+    for f in [os.path.join(d, fname) for d in search_dirs]:
+        if os.path.isfile(f):
+            return f
+
+def open_file(fname, mode='r'):
+    if fname == '-':
+        if 'w' in mode:
+            return sys.stdout.buffer
+        return sys.stdin
+    try:
+        if 'b' in mode:
+            return open(fname, mode)
+        return open(fname, mode, encoding='utf-8')
+    except IOError as e:
+        if e.errno == 2:
+            raise SkoolKitError('{0}: file not found'.format(fname))
+        raise
+    except TypeError:
+        # Assume this is already a file-like object
+        return fname
+
+def read_bin_file(fname, size=-1):
+    if fname == '-':
+        return sys.stdin.buffer.read(size)
+    try:
+        with open(fname, 'rb') as f:
+            return f.read(size)
+    except IOError as e:
+        if e.errno == 2:
+            raise SkoolKitError('{0}: file not found'.format(fname))
+        raise
+
+def format_template(template__, name__, **fields):
+    try:
+        return template__.format(**fields)
+    except ValueError as e:
+        raise SkoolKitError('Failed to format {} template: {}'.format(name__, e.args[0]))
+    except KeyError as e:
+        raise SkoolKitError("Unknown field '{}' in {} template".format(e.args[0], name__))
+
+def normpath(*paths):
+    return posixpath.normpath(posixpath.join(*[p.replace('\\', '/') for p in paths]))
+
+def get_word(data, index):
+    return data[index] + 256 * data[index + 1]
+
+def get_word3(data, index):
+    return get_word(data, index) + 65536 * data[index + 2]
+
+def as_dword(num):
+    return (num % 256, (num >> 8) % 256, (num >> 16) % 256, (num >> 24) % 256)
+
+def get_dword(data, index):
+    return get_word3(data, index) + 16777216 * data[index + 3]
+
+def integer(arg):
+    try:
+        s_arg = arg.strip()
+        if s_arg.startswith('0x'):
+            return int(s_arg[2:], 16)
+        return int(s_arg)
+    except ValueError:
+        raise argparse.ArgumentTypeError("invalid integer: '{}'".format(arg))
+
+def eval_variable(name, value):
+    if name.endswith('$'):
+        return value
+    return evaluate(value)
+
+def variable(arg):
+    name, sep, value = arg.partition('=')
+    if name and sep:
+        try:
+            return name, eval_variable(name, value)
+        except ValueError:
+            raise argparse.ArgumentTypeError("invalid arithmetic expression: '{}'".format(arg))
+    elif name:
+        raise argparse.ArgumentTypeError("missing variable value: '{}'".format(arg))
+    else:
+        raise argparse.ArgumentTypeError("missing variable name: '{}'".format(arg))
+
+class SkoolKitError(Exception):
+    pass
+
+# API (ControlDirectiveComposer)
+class SkoolParsingError(SkoolKitError):
+    """Raised when an error occurs while parsing a skool file."""

skoolkit/audio.py

@@ -0,0 +1,186 @@
+# © 2013, 2014, 2022-2024, 2026 Richard Dymond (rjdymond@gmail.com)
+#
+# This file is part of SkoolKit.
+#
+# SkoolKit is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# SkoolKit is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# SkoolKit. If not, see <http://www.gnu.org/licenses/>.
+
+from math import ceil
+from struct import pack
+
+from skoolkit.simutils import CLOCK_SPEEDS, CONTENTION_INTERVALS, FRAME_DURATIONS
+
+CLOCK_SPEED = 'ClockSpeed'
+CONTENTION_BEGIN = 'ContentionBegin'
+CONTENTION_END = 'ContentionEnd'
+CONTENTION_FACTOR = 'ContentionFactor'
+FRAME_DURATION = 'FrameDuration'
+INTERRUPT_DELAY = 'InterruptDelay'
+SAMPLE_RATE = 'SampleRate'
+
+def moving_average_filter(delays, options, volume=1):
+    sample_delay = options[CLOCK_SPEED] / options[SAMPLE_RATE]
+    s0, s1 = 0, sample_delay
+    t, t1 = 0, ceil(s1)
+    bit = bits = 0
+    samples = []
+    for d in delays:
+        while True:
+            if t + d < t1:
+                if bit:
+                    bits += d
+                t += d
+                break
+            i = t1 - t
+            if bit:
+                bits += i
+            d -= i
+            samples.append(volume * bits / (t1 - s0))
+            s0 = t = t1
+            s1 += sample_delay
+            t1 = ceil(s1)
+            bits = 0
+        bit = 1 - bit
+    return samples
+
+def write_wav(audio_file, samples, sample_rate, channels=1):
+    bits_per_sample = 16
+    bytes_per_sample = (bits_per_sample // 8) * channels
+    byte_rate = bytes_per_sample * sample_rate
+    data_length = bytes_per_sample * len(samples) // channels
+    header = bytearray()
+    header.extend(b'RIFF')
+    header.extend(pack('<I', 36 + data_length))
+    header.extend(b'WAVEfmt ')
+    header.extend(pack('<IH', 16, 1)) # length of fmt chunk, format (PCM)
+    header.extend(pack('<HIIHH', channels, sample_rate, byte_rate, bytes_per_sample, bits_per_sample))
+    header.extend(b'data')
+    header.extend(pack('<I', data_length))
+    audio_file.write(header)
+    for sample in samples:
+        audio_file.write(pack('<h', round(sample * 0xFFFF) - 0x8000))
+
+class AudioWriter:
+    """
+    Initialise the audio writer.
+
+    :param config: A dictionary constructed from the contents of the
+                   :ref:`ref-AudioWriter` section of the ref file.
+    """
+    # Component API
+    def __init__(self, config=None):
+        self.options = ({
+            CLOCK_SPEED: CLOCK_SPEEDS[0],
+            CONTENTION_BEGIN: CONTENTION_INTERVALS[0][0],
+            CONTENTION_END: CONTENTION_INTERVALS[0][1],
+            CONTENTION_FACTOR: 51,
+            FRAME_DURATION: FRAME_DURATIONS[0],
+            INTERRUPT_DELAY: (895,),
+            SAMPLE_RATE: 44100
+        }, {
+            CLOCK_SPEED: CLOCK_SPEEDS[1],
+            CONTENTION_BEGIN: CONTENTION_INTERVALS[1][0],
+            CONTENTION_END: CONTENTION_INTERVALS[1][1],
+            CONTENTION_FACTOR: 51,
+            FRAME_DURATION: FRAME_DURATIONS[1],
+            INTERRUPT_DELAY: (1385, 1565),
+            SAMPLE_RATE: 44100
+        })
+        if config:
+            for k, v in config.items():
+                try:
+                    if k == INTERRUPT_DELAY:
+                        self.options[0][k] = self.options[1][k] = tuple(int(n) for n in v.split(','))
+                    else:
+                        self.options[0][k] = self.options[1][k] = int(v)
+                except ValueError:
+                    pass
+
+    # Component API
+    def write_audio(self, audio_file, delays, contention=False, interrupts=False, offset=0, is128k=False):
+        """
+        Write an audio file.
+
+        :param audio_file: The file object to write the audio to.
+        :param delays: A sequence of integers representing the intervals (in
+                       T-states) between speaker flips.
+        :param contention: Whether to simulate additional delays due to memory
+                           and I/O contention.
+        :param interrupts: Whether to simulate additional delays due to
+                           interrupts.
+        :param offset: The offset (in T-states) of the first speaker flip from
+                       the start of the frame. Used when simulating delays due
+                       to contention and interrupts.
+        :param is128k: Whether to use 128K timings.
+        """
+        options = self.options[is128k]
+        if contention or interrupts:
+            self._add_contention(delays, contention, interrupts, offset, options)
+        samples = moving_average_filter(delays, options)
+        write_wav(audio_file, samples, options[SAMPLE_RATE])
+
+    # Component API
+    def formats(self):
+        """
+        Return a sequence of filename extensions (including the '.')
+        corresponding to the audio formats supported by this writer.
+        """
+        return ('.wav',)
+
+    def _add_contention(self, delays, contention, interrupts, cycle, options):
+        c_begin, c_end = options[CONTENTION_BEGIN], options[CONTENTION_END]
+        c_factor = 1 + options[CONTENTION_FACTOR] / 100
+        i_delays = options[INTERRUPT_DELAY]
+        i_delays_idx = 0
+        f_duration = options[FRAME_DURATION]
+
+        for i in range(len(delays)):
+            d_offset = 0
+            while 1:
+                if interrupts and cycle == 0:
+                    cycle = i_delays[i_delays_idx]
+                    if i:
+                        delays[i] += i_delays[i_delays_idx]
+                        d_offset += i_delays[i_delays_idx]
+                    i_delays_idx = (i_delays_idx + 1) % len(i_delays)
+                d_remaining = delays[i] - d_offset
+                if contention and cycle < c_end:
+                    if cycle < c_begin:
+                        gap = c_begin - cycle
+                        if d_offset + gap >= delays[i]:
+                            # Delay ends before next contended interval starts
+                            cycle += d_remaining
+                            break
+                        # Delay crosses into contended interval
+                        d_offset += gap
+                        cycle = c_begin
+                    else:
+                        c_period = c_end - cycle
+                        d_rem_contended = int(d_remaining * c_factor)
+                        if d_rem_contended < c_period:
+                            # Delay ends within contended interval
+                            delays[i] = d_offset + d_rem_contended
+                            cycle += d_rem_contended
+                            break
+                        # Delay crosses into uncontended interval
+                        cd_cycles = int(c_period / c_factor)
+                        delays[i] += c_period - cd_cycles
+                        d_offset += cd_cycles
+                        cycle = c_end
+                else:
+                    if d_remaining < f_duration - cycle:
+                        # Delay ends before frame boundary
+                        cycle += d_remaining
+                        break
+                    # Delay crosses frame boundary
+                    d_offset += f_duration - cycle
+                    cycle = 0

skoolkit/ay.py

@@ -0,0 +1,251 @@
+# © 2026 Richard Dymond (rjdymond@gmail.com)
+#
+# This file is part of SkoolKit.
+#
+# SkoolKit is free software: you can redistribute it and/or modify it under the
+# terms of the GNU General Public License as published by the Free Software
+# Foundation, either version 3 of the License, or (at your option) any later
+# version.
+#
+# SkoolKit is distributed in the hope that it will be useful, but WITHOUT ANY
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along with
+# SkoolKit. If not, see <http://www.gnu.org/licenses/>.
+
+from skoolkit.audio import (CLOCK_SPEED, FRAME_DURATION, SAMPLE_RATE,
+                            moving_average_filter, write_wav)
+from skoolkit.simutils import CLOCK_SPEEDS, FRAME_DURATIONS
+
+AY_CLOCK_RATE = 1773400
+AY_DAC_TABLE = tuple(v / 0xFFFF for v in (
+    0x0000, 0x0385, 0x053D, 0x0770, 0x0AD7, 0x0FD5, 0x15B0, 0x230C,
+    0x2B4C, 0x43C1, 0x5A4B, 0x732F, 0x9204, 0xAFF1, 0xD921, 0xFFFF
+))
+
+class Channel:
+    def __init__(self, pan):
+        self.volume = 0
+        self.tone = 0
+        self.tone_counter = 0
+        self.tone_period = 1
+        self.t_off = 0
+        self.n_off = 0
+        self.e_on = 0
+        self.pan_left = 1 - pan
+        self.pan_right = pan
+
+class Interpolator:
+    def __init__(self):
+        self.c = [0] * 4
+        self.y = [0] * 4
+
+class AY:
+    def __init__(self, sample_rate):
+        self.interpolator_left = Interpolator()
+        self.interpolator_right = Interpolator()
+        self.x = 0
+        self.step = AY_CLOCK_RATE / (sample_rate * 64)
+        self.noise = 1
+        self.noise_counter = 0
+        self.noise_period = 0
+        self.left = 0
+        self.right = 0
+        self.envelope = 0
+        self.envelope_shape = 0
+        self.envelope_counter = 0
+        self.envelope_segment = 0
+        self.envelope_period = 1
+        self.sample_rate = sample_rate
+        slide_down = (self.slide_down, 31)
+        slide_up = (self.slide_up, 0)
+        hold_bottom = (self.hold, 0)
+        hold_top = (self.hold, 31)
+        self.envelopes = (
+            (slide_down, hold_bottom),
+            (slide_down, hold_bottom),
+            (slide_down, hold_bottom),
+            (slide_down, hold_bottom),
+            (slide_up, hold_bottom),
+            (slide_up, hold_bottom),
+            (slide_up, hold_bottom),
+            (slide_up, hold_bottom),
+            (slide_down, slide_down),
+            (slide_down, hold_bottom),
+            (slide_down, slide_up),
+            (slide_down, hold_top),
+            (slide_up, slide_up),
+            (slide_up, hold_top),
+            (slide_up, slide_down),
+            (slide_up, hold_bottom)
+        )
+        self.channels = (Channel(0.5), Channel(0.5), Channel(0.5))
+        self.update_state([0] * 16)
+
+    def update_mixer(self):
+        self.noise_counter += 1
+        if self.noise_counter >= self.noise_period * 2:
+            self.noise_counter = 0
+            self.noise = (self.noise // 2) | (((self.noise ^ (self.noise // 8)) & 1) * 65536)
+        noise = self.noise & 1
+
+        self.envelope_counter += 1
+        if self.envelope_counter >= self.envelope_period:
+            self.envelope_counter = 0
+            self.envelopes[self.envelope_shape][self.envelope_segment][0]()
+
+        self.left = 0
+        self.right = 0
+
+        for channel in self.channels:
+            channel.tone_counter += 1
+            if channel.tone_counter >= channel.tone_period:
+                channel.tone_counter = 0
+                channel.tone ^= 1
+            out = (channel.tone | channel.t_off) & (noise | channel.n_off)
+            out *= self.envelope // 2 if channel.e_on else channel.volume
+            self.left += AY_DAC_TABLE[out] * channel.pan_left
+            self.right += AY_DAC_TABLE[out] * channel.pan_right
+
+    def update_state(self, r):
+        for i, channel in enumerate(self.channels):
+            channel.tone_period = ((r[2 * i] + 256 * r[2 * i + 1]) & 0x0FFF) or 1
+            channel.t_off = (r[7] >> i) & 1
+            channel.n_off = (r[7] >> (i + 3)) & 1
+            channel.e_on = r[8 + i] & 16
+            channel.volume = r[8 + i] % 16
+
+        self.noise_period = (r[6] & 0x1F) or 1
+        self.envelope_period = (r[11] + 256 * r[12]) or 1
+
+        if r[13] >= 0:
+            self.envelope_shape = r[13] % 16
+            self.envelope_counter = 0
+            self.envelope_segment = 0
+            self.envelope = self.envelopes[self.envelope_shape][0][1]
+            r[13] = -1
+
+    def frames(self, ay_log, ay_res):
+        ay = [0] * 16
+        frame = -1
+        t0 = ay_log[0][0]
+        for tstates, reg, value in ay_log:
+            if frame >= 0:
+                nframe = tstates // ay_res
+                while nframe > frame:
+                    yield ay
+                    nframe -= 1
+            frame = tstates // ay_res
+            ay[reg] = value
+
+    def slide_up(self):
+        self.envelope += 1
+        if self.envelope > 31:
+            self.envelope_segment ^= 1
+            self.envelope = self.envelopes[self.envelope_shape][self.envelope_segment][1]
+
+    def slide_down(self):
+        self.envelope -= 1
+        if self.envelope < 0:
+            self.envelope_segment ^= 1
+            self.envelope = self.envelopes[self.envelope_shape][self.envelope_segment][1]
+
+    def hold(self):
+        return
+
+    def render(self, ay_log, frame_duration, ay_res, volume):
+        samples = []
+        frame_rate = 50 * frame_duration / ay_res
+        fstep = frame_rate / self.sample_rate
+        fcounter = 1
+        frames = self.frames(ay_log, ay_res)
+        while True:
+            fcounter += fstep
+            while fcounter >= 1:
+                # Load next frame of data to AY registers
+                fcounter -= 1
+                frame = next(frames, None)
+                if frame:
+                    self.update_state(frame)
+                else:
+                    break
+            if frame is None:
+                break
+
+            # Generate and store next sample
+            for i in range(8):
+                self.x += self.step
+                if self.x >= 1:
+                    self.x -= 1
+                    self.update_mixer()
+            samples.append(self.left * volume)
+            samples.append(self.right * volume)
+
+        return samples
+
+class Options:
+    def __init__(self, volume=100, ay_res=None, beeper=False):
+        self.volume = volume
+        self.ay_res = ay_res
+        self.beeper = beeper
+
+class AYAudioWriter:
+    def __init__(self, config=None):
+        self.options = {
+            CLOCK_SPEED: CLOCK_SPEEDS[1],
+            FRAME_DURATION: FRAME_DURATIONS[1],
+            SAMPLE_RATE: 44100
+        }
+        if config:
+            for k, v in config.items():
+                try:
+                    self.options[k] = int(v)
+                except ValueError:
+                    pass
+
+    def write_audio(self, audio_file, audio_log, options):
+        volume = min(max(0, options.volume), 100) / 100
+        ay_volume = volume * 2 / 3
+        ay_log, beeper_log = self._parse_log(audio_log)
+        if options.beeper and beeper_log:
+            # Synchronise log start times
+            if ay_log and ay_log[0][0] < beeper_log[0]:
+                beeper_log.insert(0, ay_log[0][0])
+            else:
+                ay_log.insert(0, (beeper_log[0], 0, 0))
+        ay = AY(self.options[SAMPLE_RATE])
+        frame_duration = self.options[FRAME_DURATION]
+        ay_res = options.ay_res or 622 # 70908/622=114 (5700Hz)
+        ay_samples = ay.render(ay_log, frame_duration, ay_res, ay_volume)
+        if options.beeper and beeper_log:
+            delays = [t1 - t0 for t0, t1 in zip(beeper_log, beeper_log[1:])]
+            beeper_samples = moving_average_filter(delays, self.options, volume)
+            samples = self._combine(ay_samples, beeper_samples)
+        else:
+            samples = ay_samples
+        write_wav(audio_file, samples[::2], self.options[SAMPLE_RATE])
+
+    def _parse_log(self, audio_log):
+        ay_log = []
+        beeper_log = []
+        for record in audio_log:
+            if record[1] < 16:
+                ay_log.append(record)
+            else:
+                beeper_log.append(record[0])
+        return ay_log, beeper_log
+
+    def _combine(self, ay_samples, beeper_samples):
+        samples = []
+        ay_len = len(ay_samples) // 2
+        beeper_len = len(beeper_samples)
+        max_len = max(ay_len, beeper_len)
+        ay_samples.extend([0] * ((max_len - ay_len) * 2))
+        beeper_samples.extend([0] * (max_len - beeper_len))
+        for i in range(max_len):
+            left = (ay_samples[2 * i] + beeper_samples[i]) / 2
+            right = (ay_samples[2 * i + 1] + beeper_samples[i]) / 2
+            samples.append(left)
+            samples.append(right)
+        return samples