skoolkit 9.5__cp313-cp313-win_amd64.whl

skoolkit/__init__.py

@@ -0,0 +1,239 @@
+# Copyright 2011-2025 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: no cover
+    CSimulator = None
+
+try:
+    from skoolkit.ccmiosimulator import CCMIOSimulator
+except ImportError: # pragma: no cover
+    CCMIOSimulator = None
+
+VERSION = '9.5'
+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,211 @@
+# Copyright 2013, 2014, 2022-2024 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, floor
+
+CLOCK_SPEED = 'ClockSpeed'
+CONTENTION_BEGIN = 'ContentionBegin'
+CONTENTION_END = 'ContentionEnd'
+CONTENTION_FACTOR = 'ContentionFactor'
+FRAME_DURATION = 'FrameDuration'
+INTERRUPT_DELAY = 'InterruptDelay'
+SAMPLE_RATE = 'SampleRate'
+
+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: 3500000,
+            CONTENTION_BEGIN: 14334,
+            CONTENTION_END: 57248,
+            CONTENTION_FACTOR: 51,
+            FRAME_DURATION: 69888,
+            INTERRUPT_DELAY: 942,
+            SAMPLE_RATE: 44100
+        }, {
+            CLOCK_SPEED: 3546900,
+            CONTENTION_BEGIN: 14361,
+            CONTENTION_END: 58041,
+            CONTENTION_FACTOR: 51,
+            FRAME_DURATION: 70908,
+            INTERRUPT_DELAY: 1584,
+            SAMPLE_RATE: 44100
+        })
+        if config:
+            for k, v in config.items():
+                try:
+                    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, ma_filter=False, 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 ma_filter: Whether to apply a moving average filter.
+        :param is128k: Whether to use 128K timings.
+        """
+        options = self.options[is128k]
+        if contention or interrupts:
+            self._add_contention(delays, contention, interrupts, offset, options)
+        if ma_filter:
+            samples = self._moving_average_filter(delays, options)
+        else:
+            samples = self._delays_to_samples(delays, options)
+        self._write_wav(audio_file, samples, options)
+
+    # 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_delay = options[INTERRUPT_DELAY]
+        f_duration = options[FRAME_DURATION]
+
+        for i in range(len(delays)):
+            d_offset = 0
+            while 1:
+                if interrupts and cycle == 0:
+                    cycle = i_delay
+                    if i:
+                        delays[i] += i_delay
+                        d_offset += i_delay
+                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
+
+    def _moving_average_filter(self, delays, options):
+        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((floor(0xFFFF * bits / (t1 - s0)) - 0x8000) & 0xFFFF)
+                s0 = t = t1
+                s1 += sample_delay
+                t1 = ceil(s1)
+                bits = 0
+            bit = 1 - bit
+        return samples
+
+    def _delays_to_samples(self, delays, options):
+        sample_delay = options[CLOCK_SPEED] / options[SAMPLE_RATE]
+        samples = []
+        direction = 1
+        i = 0
+        d = delays[0]
+        t = 0
+        while 1:
+            while t >= d:
+                i += 1
+                if i >= len(delays):
+                    break
+                d += delays[i]
+                direction *= -1
+            if i >= len(delays):
+                break
+            if direction > 0:
+                samples.append(32767)
+            else:
+                samples.append(32768)
+            t += sample_delay
+        return samples
+
+    def _to_int32(self, num):
+        return (num & 255, (num >> 8) & 255, (num >> 16) & 255, num >> 24)
+
+    def _write_wav(self, audio_file, samples, options):
+        sample_rate = options[SAMPLE_RATE]
+        data_length = 2 * len(samples)
+        header = bytearray()
+        header.extend(b'RIFF')
+        header.extend(self._to_int32(36 + data_length))
+        header.extend(b'WAVEfmt ')
+        header.extend(self._to_int32(16))              # length of fmt chunk
+        header.extend((1, 0))                          # format (1=PCM)
+        header.extend((1, 0))                          # channels
+        header.extend(self._to_int32(sample_rate))     # sample rate
+        header.extend(self._to_int32(sample_rate * 2)) # byte rate
+        header.extend((2, 0))                          # bytes per sample
+        header.extend((16, 0))                         # bits per sample
+        header.extend(b'data')
+        header.extend(self._to_int32(data_length))     # length of data chunk
+        audio_file.write(header)
+        for sample in samples:
+            audio_file.write(bytes((sample & 255, sample // 256)))