#!/usr/bin/env python

"""

Acorn Electron ULA simulation.

"""

from array import array

from itertools import repeat

LINES_PER_ROW = 8       # the number of pixel lines per character row

MAX_HEIGHT = 256        # the height of the screen in pixels

MAX_WIDTH = 640         # the width of the screen in pixels

MAX_CSYNC = 2           # the scanline during which vsync ends

MIN_PIXELLINE = 38      # the first scanline involving pixel generation

MAX_SCANLINE = 312      # the number of scanlines in each frame

MAX_PIXELLINE = MIN_PIXELLINE + MAX_HEIGHT

MAX_HSYNC = 75          # the number of cycles in each hsync period

MIN_PIXELPOS = 256      # the first cycle involving pixel generation

MAX_SCANPOS = 1024      # the number of cycles in each scanline

MAX_PIXELPOS = MIN_PIXELPOS + MAX_WIDTH

SCREEN_LIMIT = 0x8000   # the first address after the screen memory

MAX_MEMORY = 0x10000    # the number of addressable memory locations

MAX_RAM = 0x10000       # the number of addressable RAM locations (64Kb in each IC)

BLANK = (0, 0, 0)

def update(ula):

    """

    Update the 'ula' for one frame. Return the resulting screen.

    """

    video = ula.video

    i = 0

    limit = MAX_SCANLINE * MAX_SCANPOS

    while i < limit:

        ula.update()

        video.update()

        i += 1

    return video.screen

class Video:

    """

    A class representing the video circuitry.

    """

    def __init__(self):

        self.screen = array("B", repeat(0, MAX_WIDTH * 3 * MAX_HEIGHT))

        self.colour = BLANK

        self.csync = 1

        self.hs = 1

        self.x = 0

        self.y = 0

    def set_csync(self, value):

        if self.csync and not value:

            self.y = 0

            self.pos = 0

        self.csync = value

    def set_hs(self, value):

        if self.hs and not value:

            self.x = 0

            self.y += 1

        self.hs = value

    def update(self):

        if MIN_PIXELLINE <= self.y < MAX_PIXELLINE:

            if MIN_PIXELPOS + 8 <= self.x < MAX_PIXELPOS + 8:

                self.screen[self.pos] = self.colour[0]; self.pos += 1

                self.screen[self.pos] = self.colour[1]; self.pos += 1

                self.screen[self.pos] = self.colour[2]; self.pos += 1

            self.x += 1

class RAM:

    """

    A class representing the RAM circuits (IC4 to IC7). Each circuit

    traditionally holds 64 kilobits, with each access obtaining 1 bit from each

    IC, and thus two accesses being required to obtain a whole byte. Here, we

    model the circuits with a list of 65536 half-bytes with each bit in a

    half-byte representing a bit stored on a separate IC.

    """

    def __init__(self):

        "Initialise the RAM circuits."

        self.memory = [0] * MAX_RAM

        self.row_address = 0

        self.column_address = 0

        self.data = 0

    def row_select(self, address):

        "The operation of asserting a row 'address' via RA0...RA7."

        self.row_address = address

    def row_deselect(self):

        pass

    def column_select(self, address):

        "The operation of asserting a column 'address' via RA0...RA7."

        self.column_address = address

        # Read the data.

        self.data = self.memory[self.row_address << 8 | self.column_address]

    def column_deselect(self):

        pass

    # Convenience methods.

    def fill(self, start, end, value):

        for i in xrange(start, end):

            self.memory[i << 1] = value >> 4

            self.memory[i << 1 | 0x1] = value & 0xf

class ShiftRegister:

    """

    A class representing a shift register, used for the internal state of the

    ULA within each 2MHz period.

    """

    def __init__(self):

        self.state = [0] * 8

        self.input = 0

    def set_input(self, input):

        self.input = input

    def shift(self):

        # NOTE: This is not meant to be "nice" Python, but instead models the

        # NOTE: propagation of state through the latches.

        self.state[0], self.state[1], self.state[2], self.state[3], \

        self.state[4], self.state[5], self.state[6], self.state[7] = \

        self.input,    self.state[0], self.state[1], self.state[2], \

        self.state[3], self.state[4], self.state[5], self.state[6]

    def __getitem__(self, i):

        return self.state[i]

class ULA:

    """

    A class providing the ULA functionality. Instances of this class refer to

    the system memory, maintain internal state (such as information about the

    current screen mode), and provide outputs (such as the current pixel

    colour).

    """

    modes = [

        (640, 1, 32), (320, 2, 32), (160, 4, 32),   # (width, depth, rows)

        (640, 1, 25), (320, 1, 32), (160, 2, 32),

        (320, 1, 25)

        ]

    palette = range(0, 8) * 2

    def __init__(self, ram, video):

        "Initialise the ULA with the given 'ram' and 'video' instances."

        self.ram = ram

        self.video = video

        self.set_mode(6)

        self.reset()

    def reset(self):

        "Reset the ULA."

        # General state.

        self.nmi = 0            # no NMI asserted initially

        self.irq_vsync = 0      # no IRQ asserted initially

        # Communication.

        self.ram_address = 0    # address given to the RAM via RA0...RA7

        self.data = 0           # data read from the RAM via RAM0...RAM3

        self.cpu_address = 0    # address selected by the CPU via A0...A15

        self.cpu_read = 0       # data read/write by the CPU selected using R/W

        # Internal state.

        self.access = 0         # counter used to determine whether a byte needs reading

        self.have_pixels = 0    # whether pixel data has been read

        self.writing_pixels = 0 # whether pixel data can be written

        self.buffer = [BLANK]*8 # pixel buffer for decoded RAM data

        self.cycle = ShiftRegister()    # 8-state counter within each 2MHz period

        self.cycle.set_input(1) # assert the input to set the first state output

        self.cycle.shift()

        self.cycle.set_input(0) # reset the input since only one state output will be active

        self.reset_vertical()

    def set_mode(self, mode):

        """

        For the given 'mode', initialise the...

          * width in pixels

          * colour depth in bits per pixel

          * number of character rows

          * character row size in bytes

          * screen size in bytes

          * default screen start address

          * horizontal pixel scaling factor

          * line spacing in pixels

          * number of entries in the pixel buffer

        The ULA should be reset after a mode switch in order to cleanly display

        a full screen.

        """

        self.width, self.depth, rows = self.modes[mode]

        columns = (self.width * self.depth) / 8                             # bits read -> bytes read

        self.access_frequency = 80 / columns                                # cycle frequency for reading bytes

        row_size = columns * LINES_PER_ROW

        # Memory access configuration.

        # Note the limitation on positioning the screen start.

        screen_size = row_size * rows

        self.screen_start = (SCREEN_LIMIT - screen_size) & 0xff00

        self.screen_size = SCREEN_LIMIT - self.screen_start

        # Scanline configuration.

        self.xscale = MAX_WIDTH / self.width                                # pixel width in display pixels

        self.spacing = MAX_HEIGHT / rows - LINES_PER_ROW                    # pixels between rows

        # Start of unused region.

        self.footer = rows * LINES_PER_ROW

        self.margin = MAX_SCANLINE - rows * (LINES_PER_ROW + self.spacing) + self.spacing

        # Internal pixel buffer size.

        self.buffer_limit = 8 / self.depth

    def vsync(self, value=0):

        "Signal the start of a frame."

        self.csync = value

        self.video.set_csync(value)

    def hsync(self, value=0):

        "Signal the end of a scanline."

        self.hs = value

        self.video.set_hs(value)

    def reset_vertical(self):

        "Signal the start of a frame."

        self.line_start = self.address = self.screen_start

        self.line = self.line_start % LINES_PER_ROW

        self.ssub = 0

        self.y = 0

        self.x = 0

    def reset_horizontal(self):

        "Reset horizontal state within the active region of the frame."

        self.y += 1

        self.x = 0

        if not self.inside_frame():

            return

        # Support spacing between character rows.

        if self.ssub:

            self.ssub -= 1

            return

        self.line += 1

        # If not on a row boundary, move to the next line.

        if self.line % LINES_PER_ROW:

            self.address = self.line_start + 1

            self.wrap_address()

        # After the end of the last line in a row, the address should already

        # have been positioned on the last line of the next column.

        else:

            self.address -= LINES_PER_ROW - 1

            self.wrap_address()

            # Test for the footer region.

            if self.spacing and self.line == self.footer:

                self.ssub = self.margin

                return

            # Support spacing between character rows.

            self.ssub = self.spacing

        self.line_start = self.address

    def in_frame(self): return MIN_PIXELLINE <= self.y < MAX_PIXELLINE

    def inside_frame(self): return MIN_PIXELLINE < self.y < MAX_PIXELLINE

    def read_pixels(self): return MIN_PIXELPOS <= self.x < MAX_PIXELPOS and self.in_frame()

    def update(self):

        """

        Update the state of the ULA for each clock cycle. This involves updating

        the pixel colour by reading from the pixel buffer.

        """

        # Detect the end of the scanline.

        if self.x == MAX_SCANPOS:

            self.reset_horizontal()

        # Detect the end of the frame.

        if self.y == MAX_SCANLINE:

            self.reset_vertical()

        # Clock management.

        access_ram = not self.nmi and self.access == 0 and self.read_pixels() and not self.ssub

        # Set row address (for ULA access only).

        if self.cycle[0]:

            # Either assert a required address or propagate the CPU address.

            if access_ram:

                self.init_row_address(self.address)

            else:

                self.init_row_address(self.cpu_address)

            # Initialise the pixel buffer if appropriate.

            if not self.writing_pixels and self.have_pixels:

                self.xcounter = self.xscale

                self.buffer_index = 0

                self.fill_pixel_buffer()

                self.writing_pixels = 1

        # Latch row address, set column address (for ULA access only).

        elif self.cycle[1]:

            # Select an address needed by the ULA or CPU.

            self.ram.row_select(self.ram_address)

            # Either assert a required address or propagate the CPU address.

            if access_ram:

                self.init_column_address(self.address, 0)

            else:

                self.init_column_address(self.cpu_address, 0)

        # Latch column address.

        elif self.cycle[2]:

            # Select an address needed by the ULA or CPU.

            self.ram.column_select(self.ram_address)

        # Read 4 bits (for ULA access only).

        # NOTE: Perhaps map alternate bits, not half-bytes.

        elif self.cycle[3]:

            # Either read from a required address or transfer CPU data.

            if access_ram:

                self.data = self.ram.data << 4

            else:

                self.cpu_transfer_high()

        # Set column address (for ULA access only).

        elif self.cycle[4]:

            self.ram.column_deselect()

            # Either assert a required address or propagate the CPU address.

            if access_ram:

                self.init_column_address(self.address, 1)

            else:

                self.init_column_address(self.cpu_address, 1)

        # Latch column address.

        elif self.cycle[5]:

            # Select an address needed by the ULA or CPU.

            self.ram.column_select(self.ram_address)

        # Read 4 bits (for ULA access only).

        # NOTE: Perhaps map alternate bits, not half-bytes.

        elif self.cycle[6]:

            # Either read from a required address or transfer CPU data.

            if access_ram:

                self.data = self.data | self.ram.data

                self.have_pixels = 1

                # Advance to the next column.

                self.address += LINES_PER_ROW

                self.wrap_address()

            else:

                self.cpu_transfer_low()

        # Reset addresses.

        elif self.cycle[7]:

            self.ram.column_deselect()

            self.ram.row_deselect()

            # Update the RAM access controller.

            self.access = (self.access + 1) % self.access_frequency

        # Update the state of the device.

        self.cycle.set_input(self.cycle[7])

        self.cycle.shift()

        # Video signalling.

        # Detect any sync conditions.

        if self.x == 0:

            self.hsync()

            if self.y == 0:

                self.vsync()

                self.irq_vsync = 0

            elif self.y == MAX_PIXELLINE:

                self.irq_vsync = 1

        # Detect the end of hsync.

        elif self.x == MAX_HSYNC:

            self.hsync(1)

        # Detect the end of vsync.

        elif self.y == MAX_CSYNC and self.x == MAX_SCANPOS / 2:

            self.vsync(1)

        # Pixel production.

        # Detect spacing between character rows.

        if not self.writing_pixels or self.ssub:

            self.video.colour = BLANK

        # For pixels within the frame, obtain and output the value.

        else:

            self.xcounter -= 1

            self.video.colour = self.buffer[self.buffer_index]

            # Scale pixels horizontally, only accessing the next pixel value

            # after the required number of scan positions.

            if self.xcounter == 0:

                self.xcounter = self.xscale

                self.buffer_index += 1

                # Handle the buffer empty condition.

                if self.buffer_index >= self.buffer_limit:

                    self.writing_pixels = 0

        self.x += 1

    def fill_pixel_buffer(self):

        """

        Fill the pixel buffer by translating memory content for the current

        mode.

        """

        byte_value = self.data # which should have been read automatically

        i = 0

        for colour in decode(byte_value, self.depth):

            self.buffer[i] = get_physical_colour(self.palette[colour])

            i += 1

    def wrap_address(self):

        if self.address >= SCREEN_LIMIT:

            self.address -= self.screen_size

    def init_row_address(self, address):

        self.ram_address = (address & 0xff80) >> 7

    def init_column_address(self, address, offset):

        self.ram_address = (address & 0x7f) << 1 | offset

    def cpu_transfer_high(self):

        if self.cpu_read:

            self.cpu_data = self.ram.data << 4

    def cpu_transfer_low(self):

        if self.cpu_read:

            self.cpu_data = self.data | self.ram.data

def get_physical_colour(value):

    """

    Return the physical colour as an RGB triple for the given 'value'.

    """

    return value & 1, value >> 1 & 1, value >> 2 & 1

def decode(value, depth):

    """

    Decode the given byte 'value' according to the 'depth' in bits per pixel,

    returning a sequence of pixel values.

    """

    if depth == 1:

        return (value >> 7, value >> 6 & 1, value >> 5 & 1, value >> 4 & 1,

                value >> 3 & 1, value >> 2 & 1, value >> 1 & 1, value & 1)

    elif depth == 2:

        return (value >> 6 & 2 | value >> 3 & 1, value >> 5 & 2 | value >> 2 & 1,

                value >> 4 & 2 | value >> 1 & 1, value >> 3 & 2 | value & 1)

    elif depth == 4:

        return (value >> 4 & 8 | value >> 3 & 4 | value >> 2 & 2 | value >> 1 & 1,

                value >> 3 & 8 | value >> 2 & 4 | value >> 1 & 2 | value & 1)

    else:

        raise ValueError, "Only depths of 1, 2 and 4 are supported, not %d." % depth

# Convenience functions.

def encode(values, depth):

    """

    Encode the given 'values' according to the 'depth' in bits per pixel,

    returning a byte value for the pixels.

    """

    result = 0

    if depth == 1:

        for value in values:

            result = result << 1 | (value & 1)

    elif depth == 2:

        for value in values:

            result = result << 1 | (value & 2) << 3 | (value & 1)

    elif depth == 4:

        for value in values:

            result = result << 1 | (value & 8) << 3 | (value & 4) << 2 | (value & 2) << 1 | (value & 1)

    else:

        raise ValueError, "Only depths of 1, 2 and 4 are supported, not %d." % depth

    return result

def get_ula():

    "Return a ULA initialised with a memory array and video."

    return ULA(get_ram(), get_video())

def get_video():

    "Return a video circuit."

    return Video()

def get_ram():

    "Return an instance representing the computer's RAM hardware."

    return RAM()

# Test program providing coverage (necessary for compilers like Shedskin).

if __name__ == "__main__":

    ula = get_ula()

    ula.set_mode(2)

    ula.reset()

    ula.ram.fill(0x5800 - 320, 0x8000, encode((2, 7), 4))

    # Make a simple two-dimensional array of tuples (three-dimensional in pygame

    # terminology).

    a = update(ula)

# vim: tabstop=4 expandtab shiftwidth=4