By Phil Ruston 2008-2013, (OSCA v676)

OSCA (Old School Computer Architecture) provides a home-computer era hardware platform for the V6Z80P. As well as basic memory and peripheral control, its features include bitmap and character mapped displays, sprites, a raster line synchronized co-pro (“LineCop”), blitter, hardware line draw and four channels of 8 bit digital sound.

Video Register Index
Video System
Display Window
Sprite System
Blitter
Line Draw
LineCop

Port Index
Audio System
Math Assist
Timer
Interrupts
OSCA ROM

In OSCA, memory and peripheral controls are accessed via the Z80's In/Out Ports. Video settings such as the palette, display controls, sprite registers etc are accessed via locations in Z80 address space (these can be paged in and out as desired). Sections of Z80 address space are also assigned to video RAM etc.

As the V6Z80P has 512KB of system RAM (and the Z80 can only see 64KB at a time), OSCA allows the user to select the sections of System RAM that appear in Z80 address space. The page size is 32KB and both the lower and upper halves of the Z80 address space can be assigned different pages of system RAM. In addition, the upper memory area can direct CPU writes to an alternative page, making data copying quicker and easier.

Depending on the memory control settings, certain sections of Z80 address space will - instead of system RAM - access components such as video/sprite memory, the video palette etc.

Diagram of Z80 Address space options under OSCA (not to scale):

The System RAM chip is 512KB. OSCA allows separate 32KB pages of this memory to appear at Z80 $0000-$7fff and $8000-$ffff. The 32KB chunk of system RAM that appears to the Z80 at $0000-$7FFF is set with the port “sys_low_page” and the 32KB of system RAM that appears to the Z80 at $8000-$FFFF is set with the port “sys_mem_select”. If required, WRITES between $8000-$FFFF can access a different page to that of READS in the same range - the write page is set with port “sys_alt_write_page”, and this feature is enabled with bit 4 of “sys_mem_select”.

Writing to Z80 address space between $0000 - $07FF:

Reading from Z80 address space between $0000 - $07FF:

¹⁾ Bits in the port “sys_alt_write_page” control whether the ROM and hardware registers or system RAM appears in locations $0000-$07ff. The default scheme (IE: when the port sys_alt_write_page is clear) is:

Video memory is a seperate 512KB RAM chip. It is normally accessed by the CPU through an 8KB window in Z80 address space. The window is located at $2000 by default but can also be at $4000, $6000, $8000, $A000, $C000 or $E000. The location of this window is set with the port “sys_vram_location” and the 8KB section of Video RAM that the window 'contains' is selected by writing to the video register “vreg_vidpage” with bit 7 clear. To access video RAM at the location specified (instead of normal System RAM), video RAM must be paged in by setting bit 6 of the port “sys_mem_select”.

(see bit 5 of “sys_mem_select”). This settings allows a 64KB page of video RAM to occupy the entire Z80 address space. This mode overrides all other paging options and forces memory WRITES from the CPU to video RAM at the page selected with bits [5:3] of “vreg_vidpage”). The CPU still reads data from ordinary system RAM (so that program code is always accessible). Because devoting the entire 64KB of Z80 address space to video RAM severely limits the CPU (calls, stack ops, IRQs, system variables etc are not possible) there is the option of excluding the first 4KB of Z80 address space from Direct Video Write Mode (set bit 6 of “sys_mem_select” as well as bit 5) - this allows access to the video registers and 2KB of system RAM at the cost of losing access to the first 4KB of each 64KB video page.

Sprite RAM is another seperate RAM chip, this time 128KB in size. It is accessible to the CPU via a 4KB window at $1000-$1FFF. To enable this window, set bit 7 of “sys_mem_select”. Note that in OSCA, sprite RAM is write only and reading from $1000-$1fff always returns values from system RAM. The 4KB page of sprite RAM that is visible to the CPU is selected by writing to the video register “vreg_vidpage” with bit 7 set.

These port locations are mainly both readable and writeable. However, the read (IN) functions can differ from the write (OUT) functions – see the individual port descriptions for details.

Read / Write: “sys_mem_select“

System RAM Upper Page Selection Table:

Notes

²⁾ When bit 4 (Alternate Write Page) is set, the UPPER 32KB page selection DURING CPU WRITES is taken from Port $0B (”sys_alt_write_page”)

³⁾ Notice 0000 and 0001 both select SYS_RAM $08000-$0FFFF at Z80: $8000-$FFFF. This prevents system RAM locations $00000-$07FFF being paged into the upper memory area. However, it is possible to override this prohibition by setting the “Any Page Mode” bit (bit 5 of port “sys_alt_write_page”) - selection 0000 will then select SYS_RAM $00000-$07FFF at Z80 $8000-$FFFF

The System RAM area where Linecop programs need to be placed are normal memory locations as far as the CPU is concerned, IE: they are not dedicated to the Linecop.

Read: “sys_irq_ps2_flags“
Interrupt status flags and PS2 port line status:

Write: “sys_irq_enable“

Interrupt masks: Allow peripheral status flags to interrupt CPU.

Read: “sys_keyboard_data“

Bits 0:7 - Data byte received from keyboard. Only read this port when the “byte received” flag (bit 0 of sys_irq_ps2_flags) is set or you may get incomplete data.

Write: “sys_clear_irq_flags“

(Bits written with ones clear the relevant IRQ flag)

Notes

• Video IRQ flag is cleared by writing $80 to ”vreg_rasthi”
• Serial IRQ flag is cleared by reading ”sys_serial_port”

Read: “sys_mouse_data“

Bits 0:7 - Data byte received from mouse. Only read this port when the “byte received” flag (bit 1 of sys_irq_ps2_flags) is set or you may get incomplete data.

Write: “sys_ps2_joy_control“

Note: Writing 1 to the keyboard (or mouse) Clock line prevents the next data byte received by the shifter from setting the keyboard (or mouse) IRQ flag (in fact it clears the IRQ flag) - this is to stop bytes written out appearing in the input buffer.

Read/write: “sys_serial_port“

Incoming or outgoing data byte for RS232 com port.

Note: When a byte is received, the “serial byte received” flag (bit 6 in Port $05) becomes set (this can cause an IRQ if desired). Reading this port clears the flag.

Read: “sys_joy_com_flags“
Joystick inputs and RS232 status.

Write: “sys_sdcard_ctrl1“

Read/Write: “sys_sdcard_ctrl2“

Read: “sys_vreg_read” - Video status register (same value as address $700)

Note: Remember, in VGA mode each scanline's data is output twice at double the normal frequency. This flag reflects the x-window of the normal PAL/NTSC ~15KHz scanline.

Write: “sys_timer“
The timer internally counts *upwards* from this value at 62.5KHz (ie: every 256 clock ticks) when it overflows, it sets the timer IRQ flag, then reloads the count from the value that was written here.

Note: Writing to this port immediately sets the timer to the written value and clears the internal prescaler count.

Read: “sys_audio_flags“

Write: “sys_audio_enable“

Read: “sys_hw_flags“

To read the hardware version word, set the address bus bits 11:8 to $0-$F when reading this port (ie: use the “OUT (C),A” instruction, presetting register B with 0 to 15). The bit addressed by B will appear in bit 7 of this port.

Write: “sys_hw_settings“

Read / Write: “sys_spi_port”

The SPI port is used by the V6Z80P to send bytes serially (MSB first, SPI mode 0) to its SD Card interface. Also, serial data received from the card's D_out line appears here for reading. See also: SPI speed setting in Port $05 and busy flag in port $09.

Read / Write: “sys_alt_write_page” ⁴⁾

(Note: uses same 32KB page selection table as “sys_low_page”)

⁴⁾ To ensure the ROM is paged in upon reset and the system can start, this port register is reset to $00 when the reset button is pressed.

Read: No function

Write: “sys_baud_rate“

Bits: [0:1] = Set serial port RS232 comms speed:

Read: “sys_eeprom_byte“

This port contains data bytes from the SPI FPGA configuration EEPROM, which can be read under CPU control. It should be read only when the “serializer status flag” (bit 4 of port ”sys_hw_flags”) is 1. Reading this port clears the internal bit count and status flag.

Handshaking: When a databurst has been initiated (see PIC comms section) the PIC issues a new byte every time the PIC CLOCK (bit 1 of ”sys_pic_comms”) is raised.

Write: “sys_pic_comms“

Read / Write: “sys_io_pins” (see data direction in port $0F)

⁵⁾ Only relevant when Reset / NMI functions are disabled by port 9 bits 0:1

Read: No function

Write: “sys_io_dir”

Read / Write: “sys_low_page”

This port selects which 32KB page from the 512KB system RAM appears at Z80 $0000-$7fff (see table below). Bear in mind the ROM/Palette, video registers and sprite page will still occupy Z80 address space locations: $0000-$01ff, $0200-$07ff and $1000-$1fff respectively regardless of which 32KB page is selected UNLESS these locations are specifically banked out of the address space with their respective control bits.

System RAM Lower Page Selection Table:

Read: No function

Write: “sys_vram_location”

Note: The video window is paged in and out of Z80 address space with bit 6 of ”sys_mem_select“

⁶⁾ 000 and 001 both set the VRAM window location at Z80 address $2000 (It is not possible to set the VRAM window to Z80 $0000).

Used by sound system, see following section.

Maths unit register mirrors (of mult_read, mult_write, mult_index).

Read: “sys_mult_read_lo“
Write: “sys_mult_write_lo“

Read: “sys_mult_read_hi“
Write: “sys_mult_write_hi“

Read: No function
Write:“sys_mult_index“

Note: The audio channel location registers were expanded to 18 bit in OSCA v672. Previously, only 128KB of System RAM ($20000-$3FFFF) was accessible to the audio system.

Ports $10-$1F and $22-$27 are assigned to the audio functions:

“audchan0_loc” Location of sound wave in System RAM Bits [bits 16:1 of sample address] (16 bit register)
—

“audchan0_len” Length of sound wave (in words) (16 bit register)
—

“audchan0_per” Period of sound wave (number of 16MHz clock ticks between sample bytes) (16 bit register)
—

“audchan0_vol” Volume of sound wave ($00-$40) (Linear scale: $40 = maximum volume) (8 bit register)
—

Same for channel 1 - “audchan1_loc”, “audchan1_len”, “audchan1_per”, “audchan1_vol“
—

Same for channel 2 - “audchan2_loc”, “audchan2_len”, “audchan2_per”, “audchan2_vol“
—

Same for channel 3 - “audchan3_loc”, “audchan3_len”, “audchan3_per”, “audchan3_vol“
—

“aud_panning” (8 bit register)

(Each bit position = one channel, IE: bit0=channel0, bit1=channel1 etc)
—

Not implemented
—

“audchan0_loc_hi” Location (high) of sound wave in System RAM [Bits 18:17] for Channel 0
—

“audchan1_loc_hi” Location (high) of sound wave in System RAM [Bits 18:17] for Channel 1
—

“audchan2_loc_hi” Location (high) of sound wave in System RAM [Bits 18:17] for Channel 2
—

“audchan3_loc_hi” Location (high) of sound wave in System RAM [Bits 18:17] for Channel 3

(These 4 location_high ports are 8 bit registers - only bits 0:1 are used)

The sound location registers are 18 bits long in total and refer to WORD addresses (not byte addresses) in System RAM (samples need to placed at word boundaries). Basically you write (the actual RAM address / 2) into the location registers.

Samples must be an even number of bytes in length - you write the length in WORDS into the Length registers (IE: Actual byte length/2). Maximum sample length is therefore 128KB.

The location (low), length and period values are 16 bit registers and should be updated by using the Z80 “OUT (C),r” instruction where C is the port number, r holds the low 8 bits of data and B holds the high 8 bits of data. The volume and location (high) ports are 8 bit registers and can be updated with the normal “OUT (n),A” instruction if desired.

The volume is a linear scale value (range: $00 = silence to $40 = full volume).

The sound sample data needs to be in signed 8-bit format and located in System RAM (it is read by the hardware using DMA). The audio hardware ignores any memory paging settings and always reads directly from the system RAM when fetching data.

The sound system operates in a similar fashion to that of the Amiga Hardware, ie: You set the location, length, period and volume of a channel, then start the channel playing with the relevant ”sys_audio_enable” port bit. Once the channel is playing, its Location and Length registers can be updated - the channel will only fetch the new values once its original length value has counted down to zero (or you stop the channel for a while and restart it). If the registers are not changed, the channel simply loops around playing the same sample data until it is stopped.

Because of the way the sound hardware pre-fetches sample data, some care needs to be taken when setting up the registers. The recommended audio register setup procedure is as follows:

1. Wait for post-audio DMA time (EG: wait for bit 6 of ”sys_vreg_read” to change)
2. Stop the relevant audio channel(s) and write location, length, period and volume.
3. Wait for next post-audio DMA time (IE: At least one scanline delay)
4. Start the relevant audio channel(s)

(Once a sample is playing, the volume and period registers can generally be updated on the fly without special regard to the DMA timing)

It's possible to use an interrupt to seamlessly switch between two or more sample buffers in order to play long samples without worrying about the exact timing. To do this you would start a channel playing, reload it with the second buffer ready for the first loop as normal, and then set up the audio interrupt so that it occurs upon the first loop (IE: just as the second buffer starts to play). In the IRQ service routine, you would set the channel location and length to point back to the first buffer, and on subsequent IRQs switch between the two buffers.

Note: The four audio loop flags are OR'd into a single interrupt source. It is up to the IRQ service routine to read bits 4:7 of the ”sys_audio_flags” port, see which bits are set (and clear them on exit from the IRQ).

Other sound related ports (see port breakdown detail above):

Port $01 (”sys_irq_enable”)- to enable/disable the audio IRQ
Port $02 (”sys_clear_irq_flags”)- to clear audio IRQ loop flags
Port $08 (”sys_audio_enable” / ”sys_audio_flags”) - to enable channels / read loop flags.

The period value is not the same as the Amiga uses, however, it has 4 times the resolution so a close match value can be obtained if desired.

Period = 16,000,000 / desired sample output rate

EG: To playback at 22050Hz, set the period to (16,000,000/22050) = 725

The minimum period value is around 512 (corresponding to a sample rate of ~31KHz) - this is because the hardware only pre-fetches 2 samples during DMA per scanline (and there is a couple of cycles overhead etc).

For pure tones, the output frequency depends on the number of samples in your waveform that constitute one cycle, so if the sample has EG: 16 bytes in one cycle, the period value required to play it at a desired frequency is calculated thus:

Period = 16,000,000 / (samples per cycle * frequency)

The default set-up is for channels 0 and 2 to go to the left side, whilst channels 1 and 3 go to the right side, but by writing to port $22 ”sys_audio_panning” all 4 channels can be individually directed to the left, right or both sides.

OSCA has a single 8 bit internal counter which continually counts upwards, once every 256 ticks of the master 16MHz clock (ie: it runs at 62.5 KHz). It is not possible to directly read the value of the counter, instead the system sets a flag every time it overflows. This flag can be used as an interrupt source.

When the counter overflows, it starts counting at whatever value was previously written to it. Writing to the port immediately sets the count to the written value and clears the internal prescaler count.

Relevant port bits:

OSCA uses interrupt mode 1, therefore all the interrupt sources when enabled cause a jump to $0038. The default OSCA ROM has the instruction JP $0A00 at this location. The following devices can cause interrupts:

Keyboard - Byte received
Mouse - Byte received
Video - Scanline Match
Timer - Overflowed
Audio - Channel Looped
Serial Port - Byte received

Before enabling a new interrupt source, ensure your IRQ handling routine will clear its IRQ flag, otherwise the system will get stuck in an IRQ service-loop.

When a full byte has been received by the internal serial-to-parallel shifter, the keyboard (or mouse) sets its “byte received” flag (see bits 0 and 1 of ”sys_irq_ps2_flags”). This flag in turn pulls the PS/2 Clock line low, meaning that the keyboard (or mouse) is blocked from sending any more data (it has to buffer it internally). If these flags are selected as an interrupt sources (see bits 0/1 of “sys_irq_enable”) then an IRQ will occur. To clear the flag, write to “sys_clear_irq_flags” with bit 0 (keyboard) or 1 (mouse) set after reading port (“sys_keyboard_data” / “sys_mouse_data”).

When the internal scanline counter matches the value written⁷⁾ to “vreg_rastlo” and “vreg_rasthi” a flag is set. To make this flag cause an interrupt, the value written to “sys_irq_enable” should have bit 3 set. To clear the video interrupt flag, write $80 to “vreg_rasthi” (this is a special case which does not affect the contents of the register).

⁷⁾ The scanline match value must between 1 and the maximum number of lines in the video mode used. (PAL: 1 to 311, VGA/NTSC 1 to 261). Setting the scanline match value to 0 currently causes undesired effects (multiple false matches) due do internal counter limitations.

When the timer has overflowed to 0, a flag will be set (see bit 2 of “sys_irq_ps2_flags”) At this point the timer reloads from the value originally written and continues. To make the overflow flag cause an interrupt, the value written to “sys_irq_enable” should have bit 2 set. To clear the timer IRQ flag write 2 to “sys_clear_irq_flags”.

The audio interrupt can be used to detect looping channels as explained in the audio section. When a channel loops it sets its associated loop flag, all 4 loop flags are OR'd together into a single IRQ source. To enable this IRQ source, the byte written to “sys_irq_enable” should have bit 4 set. To clear the audio interrupt flag, all channels' loop flags must be zero - they are reset by writing to bits 4:7 of sys_clear_irq_flags.

When a byte has been received in the internal shift buffer, a “byte received” flag becomes set (see bit 6 of “sys_joy_com_flags”). To allow this flag to cause an interrupt, the byte written to “sys_irq_enable” should have bit 6 set. Reading from “sys_serial_port” clears the byte received IRQ flag. OSCA only has a single byte serial buffer and no hardware flow control, however (unlike the keyboard and mouse) the value in the shifter is latched into a stable register until it is overwritten when the next complete byte received.

The default OSCA ROM has the instruction JP $0A03 at $0066 (the NMI Vector). The only NMI source used in OSCA is the “NMI pin” of the expansion header block. When this signal is pulled low (and the hardware NMI inhbit feature is not enabled) the Z80 /NMI line is activated, causing a jump to $66. The “NMI pin” is readable in bit 7 of “sys_io_pins” and its NMI feature can be disabled by setting bit 0 of “sys_hw_settings”.

The maths assist unit consists of 3 elements:

1. A 256 word table which can hold values (such as sine constants)
2. A 16bit value that is multiplied by the values in the table
3. An index byte to select which word in the table to multiply by

The multiplication is a sign extended 16 bit x 16 bit operation, but only 16 bits from the resulting 32 bit longword are available to be read, these bits are taken from bit 29 to bit 14. (Therefore care should be taken with the values used in the multiplication operation to 1. get correct results for unscaled multiplies and 2. prevent overflows.)

The maths unit can be used for fast scaling of values using just the first entry of the table. For example you could write some value to be scaled into the mult_table(0), set the mult_index at 0 and write the scaling factor from 0 to 16384 into “mult_write”. The output from “mult_read” will be mult_table(0) * mult_write/16384

To use the maths unit as a simple 256 x 16bit look-up table, write your 16 bit words in the mult_table, put 16384 into mult_write and simply select the value by setting mult_index and reading from mult_read.

To do an unscaled “multiply by a constant” (using only a single entry in the table) you need to adjust the multiplier and multiplicand to counter the scaling of the output. EG: To multiply $0087 by $0025 you could write $8700 into mult_write - (IE: a simple LSB/MSB byte swap) and $0940 into mult_table(0) (IE: $25 * $40). As the second word needs more processing, this would be your pre-set constant (you could fill the rest of the table with other constants if desired).

The maths unit makes sin/cos calculations straightforward: Write the table with 256 sine values (maximum positive amplitude = 16384), set the multiplier word to coordinate x and the index byte to the angle a, the resulting word will be SIN (a) * x

Registers / locations used by the maths unit:

In OSCA v676+ mult_write, mult_read and mult_index are also accessible via IO ports:

Port $28 : sys_mult_read_lo, sys_mult_write_lo
Port $29 : sys_mult_read_hi, sys_mult_write_hi
Port $2A : sys_mult_index

There is 512KB of “background video” RAM available (separate to sprite, audio and system memory). It is normally accessible to the CPU in 8KB pages (at Z80 address $2000, $4000, $6000, $8000, $A000, $C000 or $E000 depending on the port setting “sys_vram_location”) with the page selected by the video register “vreg_vidpage”. However, a special write-only mode also allows the entire Z80 address space to be mapped onto a 64KB page of video RAM.

There are two main video modes, bitmap and tilemap - both allow up to 256 colours. The display is normally non-interlaced, PAL ~50Hz or VGA/NTSC ~60Hz (there is an option to force VGA to non-standard 50Hz). CPU access TO VIDEO MEMORY whilst the display window is being generated is blocked by the video system. The different video modes affect how long the CPU is kept waiting - Dual Playfield tilemap mode is the most demanding.

In standard chunky bitmap mode pixel data is fetched in a simple 1 byte = 1 pixel fashion (it is called “chunky” as all the bits for each pixel come from the same 'chunk' - IE: location - in memory).

The byte fetched from VRAM represents an index in the video palette, therefore a $00 shows a “palette entry 0” coloured pixel, $01 shows a “palette entry 1” coloured pixel and so on. Data is fetched linearly from VRAM left to right, top to bottom of the screen. The data-fetch start address can be manipulated to achieve smooth scrolling effects.

Fast line draws (125ns per 256 colour pixel) are possible in chunky mode. The hardware requires Bresenham constants, octant number, video start address and length of line to be set up in the line draw registers, then the hardware carries out the algorithm. The registers are doubled up, allowing line set-up data for a new line to be loaded up whilst the previous line is being drawn.

(Simplified in OSCA 672)

Chunky mode also offers “pixel flooding” (see bit 6 of “vreg_vidctrl”) which repeats the last pixel colour to achieve flood fill effects. In this mode, the hardware XOR's each new pixel with the value of the last. The stored colour is reset to zero at the start of each scan line.

Finally, in chunky mode pixels can be horizontally expanded from 1 to 8 times (see bit 3 of “vreg_vidctrl” and bits 0:2 “vreg_yhws_bplcount”)

In planar mode the display can have up to 8 bitplanes which are internally combined to form a palette index for each pixel. As the number of bitplanes can be set (see “vreg_yhws_bplcount”), the maximum number of colours on screen (without reloading the palette registers mid-screen) can be 2,4,8,16,32,64,128 or 256. This can offer efficiencies in terms of video memory use and update speed. The main disadvantage is that fine pixel-level access is more difficult. The bitplane location address registers can be manipulated to achieve scrolling effects etc. (Fine horizontal pixel scrolling is provided via a hardware scroll register (“vreg_xhws”).

The diagram below shows how bitplane data is combined to form a pixel's palette index:

To set the location of display data, write to the Bitplane Location Registers at $240-$27F (see register index for details). The location registers need only be written once, an internal counter adds an offset internally as the frame is built up (this offset register can be reset at any time). For convenience, there are in fact two sets of location registers - the video hardware uses the set determined by bit 5 of the video register “vreg_vidctrl”.

A modulo register is provided also - this can be used to skip bytes at the end of each scan line - useful for hiding new scroll data, interlaced displays etc.

In tile-map mode the display is built up in a less direct manner: The hardware reads a look-up table to display a predefined block for each tile position. The blocks can be 8×8 or 16×16 pixels in size (defined in a simple, linear “1 byte = 1 pixel colour index” left to right, top to bottom fashion). Dual playfield capability is provided so that one map can be overlaid on top of the other (pixels of value 0 are taken as transparent). The playfield priority is selectable. Each playfield can be offset by 0-15 pixels in the vertical or horizontal direction allowing smooth scrolling. There are two map buffers per playfield which allows double buffering if desired. The registers “vreg_vidctrl”, “vreg_ext_vidctrl”, “vreg_xhws” and “vreg_yhws_bplcount” contain the control bits for the tilemap modes.

The most basic OSCA tilemap mode limits tiles to 16×16 pixels, indexed with single bytes allowing a maximum of 256 different tiles. Two sets of tile definitions are available with 248 and 256 tile images respectively (Tile set A has fewer definition blocks available because the video memory for blocks 0-7 (VRAM $0-$7ff) is assigned for use as the four available tile maps.) This simplistic system is referred to as “Legacy Tilemap mode”. Extended Tile Mode provides more flexibility and may be a better choice for new programs.

In Legacy Tile Mode the Video RAM is organized as follows:

The horizontal size of the tile map buffer is always 32 bytes, no matter what the size of the display window.

In Extended Tilemap Mode (IE: when bit 0 of “vreg_ext_vidctrl” is set), tiles are indexed by 2 bytes and can be 16×16 or 8×8 pixels. There is a single set⁸⁾ of 2048 16×16 tiles or 8192 8×8 tiles (the “tile set select” bits used in legacy mode have new meanings in Extended Tilemap Mode.) The tile maps are located between at $70000- $73fff in video memory, well clear of the tile definitions which are located at VRAM $0 (The memory space used by the tile maps will produce garbage tiles if indexed). Bits 6:7 of the upper byte of the tile indices control x_mirror (Bit 6) and y_flip (Bit 7) of each tile definition.

⁸⁾Although the tile definitions are normally indexed in a straightforward linear manner, there is an option to switch between the definitions held at VRAM $0-$3FFFF and $40000-$7ffff.

In Extended Tile Mode with 16×16 tiles VRAM is organised as follows:

In 16×16 tilemap mode, the width of each horizontal map line is 32 bytes no matter what the size of the display window. Each tilemap has room for 16 rows of tiles (ie: a 256 scanline display), however when using vertical hardware scroll, the maximum y window should be 240 lines to mask off the last tile-line (where the internal tilemap line pointer wraps back to 0).

In Extended Tile Mode with 8×8 tiles VRAM is organised as follows:

(Notice that the LSB/MSB arrangement is slightly different to that of the 16×16 mode.)

In 8×8 tilemap mode, the width of each horizontal map line is 64 bytes no matter what the size of display window. The hardware scroll registers still provide a 0-15 pixel offset.

Each tilemap has room for 32 rows of tiles (ie: a 256 scanline display), however when using vertical hardware scroll, the maximum y window should be 248 lines to mask off the last tile-line (where the internal tilemap line pointer wraps back to 0).

The V6Z80P's colour resolution is 12 bit, with 4 bits for red, green and blue (allowing a choice of 4096 colours). OSCA uses an indexed colour system with 256 colour registers. Each palette entry is a 16 bit word with bits arranged as follows:

Example palette writes:

EG:  LD HL,$0F0F        
     LD (PALETTE),HL    ; Set colour0 (background) to magenta

EG:  LD HL,$00F0        
     LD (PALETTE+2),HL  ; Set colour1 to green

Notes:

• There are actually two palettes, allowing buffering etc. Either palette can be set to “live” status (IE: accessed by the video hardware to build the video frame) or “target” (IE: receives writes from the CPU / LineCop). This is set with the register “vreg_palette_ctrl”.

• The palettes are write-only and located in the same memory space (0-$1ff) as the FPGA-based ROM. This is convenient since the ROM is read-only and palette is write-only. However, system RAM can be paged into this location if desired, see: “sys_alt_write_page”

The position of the edges of the display window within the maximum visible TV screen are programmable (which - of course - sets the size of the window). There are 16 possible locations each for “X Start”, “X Stop”, “Y Start” and “Y Stop”. Each horizontal step is 16 pixels wide, and each vertical step is 8 lines tall.

The register “vreg_window_size” sets the position of the display window. Note: both vertical and horizontal location settings are written this same register, its function changes depending on bit 2 of “vreg_rasthi” (see the example at the end of this section).

X_START and X_STOP

When writing to the “vreg_window_size” register to set the horizontal positioning, the byte should be composed as follows:

(Make sure vreg_rasthi was previously written with a value that has bit 2 set.)

The table below shows all the possible combinations of X_START (the green rows) and X_STOP (blue columns). Where a column and row intersect, the value is the width of the display in pixels. Note: X_Start values 0-4 (in red) are positioned well off the left hand side of the display so should not be used. A good, centralized 320 pixel wide display choice would be the value $8C.

Theory
The X_Start and X_Stop values correspond to bits [7:4] of an internal low-res pixel clock counter (which counts from 0-511 on each scanline). X_Start values cover the count range 0,16,32,48 etc (the beam actually enters the left side of the visible (PAL TV) display somewhere around count = 96).

X_Stop values cover the count range 256,272,288,304 etc (the raster beam leaves the display somewhere around count 496) Note: X_Stop 0 (count = 256) is not the exact middle of the visible display because the TV's raster beam does not advance during sync periods (at the extreme left of the display).

Y_START and Y_STOP

When writing to the vreg_window_size register, the byte should be composed as follows:

(Make sure vreg_rasthi was previously written with a value that has bit 2 clear.)

The table below shows all the possible combinations of Y_START (the green rows) and Y_STOP (blue columns). Where a column and row intersect, the value is the height of the display in scanlines. Note: Y_Start values 0-1 (in red) are above the top of the display so should not be used. A good, centralized 200 line wide display choice would be the value $5A.

Theory
The Y_Start and Y_Stop values correspond to bits [6:3] of the internal scanline counter. Y_Start covers the range of scanlines 0-120 and Y_Stop covers the range of scanlines 160-280.

Because PAL/NTSC/VGA use differing amounts of scanlines to make up a full display, if Y_START and Y_STOP values are chosen to vertically centre a window, that window will be offset in other video modes. If vertical centring is important, a program must detect the video mode and adjust Y_Start and Y_Stop accordingly - note that this will also mean adjusting your Sprite and Linecop coordinates. The 60Hz mode flag in the Video Status Register can assist if the correction is to be done automatically, or a display adjust routine can be provided in user programs.

Example code - Display Window setting:

To set the vertical start and stop positions of the display window, first write “vreg_rasthi” with bit 2 clear, then write an appropriate value from the tables above to “vreg_window_size”. To set the horizontal positions, write “vreg_rasthi” with bit 2 set, then write an appropriate value for the horizontal setting to “vreg_window_size”.

EG:
    ld a,$00
    ld (vreg_rasthi),a        ; selects vertical window setting
    ld a,$5a
    ld (vreg_window_size),a   ; sets vertical window size/position (200 lines)
    ld a,$04
    ld (vreg_rasthi),a        ; selects horizontal window setting
    ld a,$8c
    ld (vreg_window_size),a   ; sets horizontal window size/position (320 pixels

There is 128KB of dedicated RAM for sprite definitions (enough space for 512 16×16 256 colour sprite blocks). This (write only) memory is accessed in 4KB pages through a window in Z80 address space located at $1000-$1FFF. The 4KB page from within the total 128KB sprite RAM is selected by the register “vreg_vidpage” (write the page number 0-31, with bit 7 set). The 4KB window is opened and closed with Bit 7 of the port “sys_mem_select”. (Note: When the CPU reads from $1000-$1FFF, data is ALWAYS returned from system RAM regardless of the setting in “sys_mem_select”.)

Sprite definition memory accepts writes at full speed when the sprites are disabled. When sprites are enabled, writes from the CPU are forced to wait until the sprite hardware releases the RAM buses. The length of the wait during contention depends how busy the sprite hardware is on any given scanline. Access to the sprite control registers is never subject to contention.

Each sprite definition block is 256 bytes long, with pixel data in a linear format “1 byte = 1 pixel” fashion, left to right, top to bottom of the sprite definition. Colour index zero is considered transparent by the sprite video hardware. Sprites are always 16 pixels wide but can be up to 240 pixels tall (the height of an individual sprite (in 16 line blocks) is set by its control register). The additional definition data for sprites taller than 16 lines comes from the blocks of sprite data following the specified sprite definition. Sprite images can be individually mirrored horizontally by setting a bit in their control registers - see detail below.

There is enough time on any one scanline to show 55 sprites, but there are 127 sprite control registers. Therefore, this can be thought of as hardware multiplexing: Because it is uncommon for 55 sprites to appear on the same line, sprite images from all the registers will normally be displayed if spread throughout the entire display window.

A double buffering mode allows half the sprite registers to be updated whilst the sprite hardware builds the display from the other half (the buffers are typically switched by the user's program each frame). This removes possible on-screen glitches and/or the need to dump data to the sprite registers off-screen. Bits in “vreg_sprctrl” are used operate this mode.

In the most basic mode, non-zero sprite pixels appear in front of all background display data. However there are controls to allow sprites to be masked by sections of the background colour palette. For the purposes of priority, the background palette is divided into 16 x 16 colour groups, sprites can then appear in front or behind one or more of these groups. There are two sets of background mask selections, sprites use the mask set based on bit 7 of their pixel colours. To dynamically switch a sprite from one set of masks to the other (EG: to move it from foreground to background) bits from a sprite’s control register can be used to modify its pixels’ MSBs (without this it would be necessary to have copies of the same sprites drawn using different colour indexes and switch the definitions.)

The main priority control “interleave mode” is bit 1 of “vreg_sprctrl”, when this bit is zero, sprite pixels appear in front of all background data. When this bit is set to one, sprites use their pixel colour index MSBs to select one of the two background mask sets.

To assist with individual sprite priorities, an option called “modify_colour_MSBs” is available, this is enabled by bit 4 in “vreg_sprctrl”. When set, the MSB of each individual sprite's height control is sacrificed and transferred the MSB of all the sprite’s pixel colours. Of course, the sprite would normally change colour if the palette indices 1-127 and 129-255 are different, therefore another control bit is available that forces sprites only to be shown using colours 1-127 (IE: their pixel colour MSBs are reset to zero, but only after the priority has been determined). This option is called “fix_colours_low” and is enabled with bit 6 of “vreg_sprctrl”. (As these options sacrifice the MSB of the sprites’ height settings, it limits how tall a sprite can be.)

One last sprite feature is “matte mode” - this forces all non-zero pixels in a sprite to a single colour, an effect which is sometimes used in games to indicate a character has taken a hit. The feature is enabled with bit 5 in “vreg_sprctrl”, afterwards bit 2 of each sprite’s height control register is used to switch individual sprites to single colour. Internally, this feature sets bits 0:6 of the sprite pixels (but not bit 7, as that could affect its priority). Therefore all the sprite’s pixels will be shown as colour 127 or colour 255 depending on the sprite’s original bit 7 (if in doubt simply make palette colours 127 and 255 the same). As another bit of the sprite height control register is sacrificed, sprites are limited to 16/32/48/64 pixels tall (also 128,144, 160,176 if “modify_colour_MSBs” is not required.)

In general, bear in mind the sprite layer is generated separately (and concurrently) to the background, and because priorities work solely on colour indexes care must be taken (especially in dual playfield tile mode) when designing the colour palette and the order in which sprites are assigned to registers.

The mask registers are located at $280-$28F. Only two bits of each location are used: Bit 0 is the mask for “level 0” (where a sprite’s colour index MSB is 0) and Bit 1 is the mask for “level 1” (where a sprite’s colour index MSB is 1). The register at $280 holds the masks for background colours 0-15, the register at $281 holds the masks for background colours 16-31, the register at $282 holds the masks for background colours 32-47 and so on.

Where each register mask bit is zero, the range of colours it will represents will appear behind sprites. Where a mask bit is one, the range of colours it represents will appear in front of sprites.

An example:

$280: (background 00-0f) = 00b    $288: (background 80-8f) = 01b
$281: (background 10-1f) = 00b    $289: (background 90-9f) = 01b
$282: (background 20-2f) = 00b    $28A: (background a0-af) = 01b
$283: (background 30-3f) = 00b    $28B: (background b0-bf) = 01b
$284: (background 40-4f) = 00b    $28C: (background c0-cf) = 01b
$285: (background 50-5f) = 00b    $28D: (background d0-df) = 01b
$286: (background 60-6f) = 00b    $28E: (background e0-ef) = 01b
$287: (background 70-7f) = 00b    $28F: (background f0-ff) = 01b

In the above example (when interleave mode is enabled) sprites with pixel indexes in the range 00-7f will be occluded by background colours 80-ff. This is the default OSCA setting.

Memory addresses of registers:

$400-$5fb (127 registers - single set of sprite control registers)

or

$400-$4fb (Register bank 0) (63 registers - double buffered register mode)
$500-$5fb (Register bank 1) (63 registers - double buffered register mode)

Each sprite register is 4 sequential bytes:

$00 : X coordinate (low 8 bits)
$01 : Height, MSBs and Mirror control (see below)
$02 : Y coordinate (low 8 bits)
$03 : Definition block number (low 8 bits)

Breakdown of sub-register $01:

Sprite X and Y coordinate registers are 9 bits in size (the MSBs are stored in the second byte of the sprite's register group as shown above). The coordinate origin positions are based on the internal line counter and horizontal pixel counter as follows:

• A sprite's leftmost pixel position coincides with the leftmost display window pixel when its x coordinate = (Window_X_START * 16) - 1

• A sprite's topmost line position coincides with first display scanline when its y coordinate = (Window_Y_START * 8) + 1

EG: When using a display window [X_START=8, Y_START=5], a sprite appears in the extreme top/left of the display window when its coordinates are: x=127, y=41

Values below these positions hide parts of the sprite “behind” the border. The Window's X_START and Y_START values naturally determine how much of a sprite can be masked by the border. Horizontally, the full width of an individual sprite can be masked many times over on the left. The Y_START value allows a minimum of 16 lines of vertical (top border) masking (when using the recommended minimum Y_START of 2). If more data of a tall sprite is to be masked, then its starting definition block and height can be adjusted.

As mentioned, sprites are always 16 pixels wide, but can normally be up to 240 pixels high, with a granularity of 16 lines (as set by bits 7:4 of the second byte in each sprites control register). However, some height control bits can be sacrificed for other features:

If “modify_colour_MSBs” mode is enabled (bit 4 in “vreg_sprctrl” = 1) the four bits normally assigned to height work as follows:

Therefore in this mode sprites can be 16,32,48,64,80,96,112 (or 240 when the three height bits are all zero) lines tall.

If “matte_mode” is enabled (bit 5 in “vreg_sprctrl” = 1) the four bits normally assigned to height work as follows:

Therefore in this mode sprites can be 16,32,48,64, and 128,144,160,176 lines tall (64 lines are used when bit 0 and 1 are zero).

If both “matte_mode” and “modify_colour_MSBs” modes are selected, the four bits normally used for height are interpreted as follows:

In this mode sprites can be 16,32,48,64 lines tall (64 lines are used when bit 0 and 1 are zero).

(“LineCop”)

This simple co-processor allows changes to be made to the display at specific scan lines without having to use manual CPU interrupts (it operates using DMA cycle-stealing in a similar manner to the sound system). The LineCop system follows a program, there are 3 main instructions and each instruction is two bytes long. The upper bits of the MSB determines what kind of instruction it is:

x = Don't care
L = Line to wait for (minimum: line 1)
R = Register to update ($0-$7FF)
D = Data byte to write to selected register
a = If set: After Write, increment selected register
b = If set: After write, increment wait line (and wait)
c = If set: After write, reload LineCop Program Counter from Start Location Registers

Wait and Register Select instructions take 2 clock cycles to perform, Register Writes take 3 cycles.

The start address of the Linecop program is held in registers $20D: linecop_addr0 (bits 7:0) $20E: linecop_addr1 (bits 15:8) and $20F: linecop_addr2 (18:16) - there are some special considerations when writing to these registers:

1. Linecop programs must be aligned at even bytes in memory, however bit 0 of the address (as written to linecop_addr0) is the Linecop hardware enable control. Therefore, the value written to this register needs be an ODD number if the linecop is to run.

1. Hardware register $20f (linecop_addr2) uses the same physical address as vreg_palette_ctrl. Bit 7 selects which register is updated: 1 = write to Linecop address, 0 = Write to the palette register.

1. Write to linecop_addr0 last, so that all the other address bytes are populated whilst the linecop is inactive.

An example of setting the linecop address:

  LD C,$02 
  LD DE,$468A ;Linecop address in system memory (C:DE) is $02468A

  LD IX,linecop_addr0
  SET 7,c ;Make sure linecop register selected (set bit 7 of MSB)
  SET 0,E ;Make sure linecop enable bit is set (set bit 0 of LSB)
  LD (IX+2),C
  LD (IX+1),D
  LD (IX+0),E

The LineCop's internal Program Counter is reloaded from the address held in linecop_addr0-2 at the end of every frame and also when forced by a LineCop write instruction which has bit 12 set. As the LineCop can write to its own location pointers and restart itself, automatic list cycling / page flipping can be achieved. Linecop programs should end with a wait for a line that is never reached, IE: $1FF (Use the instruction code hexcode $C1FF).

When the raster reaches a scanline that matches that set by a LineCop wait instruction, the LineCop steals time from the CPU until it reaches the next Wait instruction. If the end of the scanline is reached first, the Linecop becomes inactive until the next frame.

You should not WAIT for Line 0 as this currently causes undesired effects due to internal counter limitations.

As the LineCop can access all the video registers including blitter etc, beware of malformed LineCop programs causing undesired effects. The linecop only ever writes to the hardware registers - never system RAM - EG: bit 7 of the port “sys_alt_write_page” is irrelevant to the LineCop.

Although the Linecop uses the same internal line counter as the sprite system, there can be a difference in the values required to achieve visual alignment between the two systems. This is because each line of sprite data (like the background video) is buffered and displayed on the next line (see hardware timing). Other systems, like the colour palette, however will respond immediately to changes and show effects on the “live” scanline. In addition, some register writes are buffered until the end of a scanline so the effect of a change may not be visible until 2 scanlines later.

A sprite y coordinate is set at $29, and appears at the top line of the display. If we wanted the Linecop to change one of its colours on its top row of pixels we should actually wait for line $2a with the Linecop. (The sprite data line is generated and buffered on line $29, but its pixels only appear a line later on line $2a).
Note: It is possible to use the dual palettes to get around this issue.

Change the background colour to white at scanline $50, and black at scan line $51

Location | Instruction
----------------------

$08000:    $c050        ; Wait for line $50
$08002:    $8000        ; Select video register $000 (background colour)
$08004:    $40ff        ; Write $ff to colour LSB, increment video register
$08006:    $20ff        ; Write $ff to colour MSB, increment wait line (and wait)
$08008:    $8000        ; Select video register $000 (background colour)
$0800A:    $4000        ; Write $00 to colour LSB, increment video register
$0800C:    $0000        ; Write $00 to colour MSB
$0800E:    $C1FF        ; Wait for line $1FF (Never reached - end of LineCop program)

Note that LineCop instruction WORDS are shown for clarity above - the BYTE ordering is Z80 standard little endian, therefore - as bytes - the code above would be listed:

$08000: $50,$c0, $00,$80, $ff,$40, $ff,$20, $00,$80, $00,$40, $00,$00, $ff,$c1

The LineCop program above can be started with the Z80 code:

 LD A,$0
 LD HL,$8000             ; LineCop program Address in A:HL = $08000 
 SET 7,A                 ; bit 7 of MSB must be set for writing to vreg_linecop_addr2 
 SET 0,L                 ; bit 0 of LSB must be set if the linecop is to run
 LD IX,linecop_addr0
 LD (IX+2),A             ; Set address MSB 
 LD (IX+1),H
 LD (IX+0),L             ; Set address LSB and start

The LineCop can be stopped with the Z80 code:

 LD A,$0                 ; Zero the accumulator
 LD (linecop_addr0),A    ; When bit 0 of this register is zero, the linecop is stopped.

OSCA’s blitter is a simple data copying engine that operates within Video RAM. It can transfer data around video memory much faster than the CPU (it copies one byte every 2 system clocks, compared with the Z80's LDIR instruction @ 1 byte per 21 clocks). Also unlike the CPU, it has 18 bit address registers so is not subject to banking issues.

The blitter can run in ascending or descending address order and has modulo registers so that a rectangular area within a larger overall array can be shifted in one operation. Source bytes that equal zero can be skipped if required - this is mainly useful in Chunky pixel mode where it can be used to mask out “transparent” pixels (eg: drawing “bobs”).

Blits take priority over access to video RAM from the CPU (but obviously the video datafetch at the start of each scanline still pauses the blitter). As long as the CPU does not access video RAM whilst a blit is underway, it will continue running its program from system RAM.

The blitter's control registers are located at $210-$21a, there are registers for:

• Source Address
• Destination Address
• Height of blit
• Width of blit
• Source modulo (bytes to skip at end of each line)
• Destination modulo (“”)
• Control (transparency mode, direction of blit, MSBs etc)

A blit operation begins whenever the width register is written. Because the CPU is not stopped by the blitter (unless it tries to access Video RAM) it can be important to test that the blitter is not already running before writing to blitter registers. A flag bit is provided in “sys_vreg_read” (bit4) for this purpose (note: some blit registers CAN be safely overwritten once a blit has started - See the blitter register list for detailed information.)

; Copy continuous 16KB block from VRAM $00000 to VRAM $08000

wait_blit: in a,(sys_vreg_read)          
           bit 4,a                       ;make sure blitter is not busy
           jr nz,wait_blit

           ld a,$00                      ;put source address in A:HL
           ld hl,$0000                   ;source is at VRAM $00000
           ld (blit_src_loc),hl          ;set source address [15:0]
           ld (blit_src_msb),a           ;set source address MSB [18:16]
           ld a,$00                      ;put source modulo in A 
           ld (blit_src_mod),a           ;set source modulo

           ld a,$00                      ;put dest address in A:HL
           ld hl,$8000                   ;destination is VRAM $08000
           ld (blit_dst_loc),hl          ;set dest address [15:0]
           ld (blit_dst_msb),a           ;set dest address MSB [18:16]
           ld a,$00                      ;put dest modulo in A
           ld (blit_dst_mod),a           ;set dest modulo
                    
           ld a,%01000000                ;set blitter control to ascending mode, modulo 
           ld (blit_misc),a              ;high bits set to zero, transparency: off

           ld a,64-1                     ;put height-1 of blit in A
           ld (blit_height),a            ;set height of blit
           ld a,256-1                    ;put width-1 of blit in A
           ld (blit_width),a             ;set width of blit and start blit 

OSCA contains a vector line drawing engine which can be used in chunky pixel mode. In a similar fashion to the blitter, this system takes priority over access to video memory and leaves the CPU free to do other things (it cannot run concurrently with the blitter, however).

The line draw hardware is an implementation of the standard Bresenham algorithm. Set up is a two-stage operation: Firstly, a table of constants must be set up - these values will be common to all lines on a given display window size so normally only needs to be set once as part of an initialization routine. This table is located at $230-$231 and is comprised of eight 16 bit constants:

a. (65536-Window width)+1
b. (65536-Window width)-1
c. Window width + 1
d. Window width - 1
e. 1
f. 65535
g. 65536 - Window width
h. Window width

Once the constants table has been set up, each line to be drawn requires registers to be set for:

• Start Address in VRAM
• Length of line
• Bresenham values
• Colour

The Bresenham value calculations do mean a certain amount of software overhead per each line to be drawn but the pay-off in speed (of the actual drawing) is more than worthwhile. The Bresenham values required are:

Constant: 2 x (dy-dx) or: 2 x (dx-dy) depending on octant
Constant: 2 x (dy) or: 2 x (dx) depending on octant

An “octant code” is required, this comprises of one bit for each of the following:

a. dx sign
b. dy sign
c. dy ⇒ dx

(Note: dx, dy = delta_x, delta_y)

The line colour is set by the register: $20b - linedraw_colour

See the linedraw register list for full details of the register set-up requirements.

The normal horizontal pixel resolution in TV mode is 8MHz and 16MHz in VGA mode - this means there can be approximately a maximum of 368 pixels visible on any one scan line. As there is spare bandwidth in TV mode, there is the option to increase the pixel rate to 16MHz, at the expense of colour depth (reduced to 16 colours max) – see bit 3 of “vreg_ext_vidctrl” - this is referred to as Hi-Res Mode. In this mode, the colour index of each normal pixel is split into two 4-bit indices (7:4 = Leftside hi-res pixel, 3:0 = Rightside hi-res pixel). This process is applied at final output stage of the pixel colour look-up and is merely a “filter” instead of a “real” hi-res mode. Because the sprite priority system is unaware of this filter, it still processes priorities based on 8 bit pixel values - therefore sprite interleaving should not be used in hi-res mode.

The vertical resolution varies depending on the TV/monitor (PAL has approx 256 visible lines, less for NTSC and VGA). The TV modes allow interlacing (see bit 2 of “vreg_ext_vidctrl”) this adjusts the frame timing causing the TV to offset the lines of every other frame by half the thickness of a scanline. (Bit 7 of “sys_vreg_read” shows which field is currently being displayed.)

As can be seen from the diagram below, each video line is internally buffered until the next scan line when it actually displayed. The sprites and background video layers are generated simultaneously to separate buffers and combined when the line is eventually clocked out to the display.

Writing to most video registers will have an immediate visible effect (EG: writes to the colour palette, unless double buffered) but some will not visibly change anything until the following scan line as changes are automatically synchronized to the start of a new scan line, these include:

• “Live Palette Select” (in vreg_palette_ctrl)
• “Live Bitplane Location Register Set Select” (also “Playfield A map buffer select” when in Tilemap mode) (bit 5 in vreg_vidctrl)
• “Tilemap Mode Select” (bit 0 in vreg_vidctrl)
• “Chunky or Planar Bitmap Mode Select” (also “Dual Playfield On/Off Select” when in Tile Map mode) (bit 7 in vreg_vidctrl)
• “Display Window Right Side Position” (in vreg_window_size)

A note concerning updating bitmap location pointers: Each line begins generation before the LineCop DMA starts, therefore even if the bitmap location registers are changed with the linecop at the start of a line (IE: immediately following a LineCop WAIT instruction) there will be some pixels at the start of the displayed line that were fetched before the pointers were changed. This can be avoided using double buffering via the 2nd bitmap location register set, alternatively the unwanted pixels can be masked with a wide border etc.

Each scanline lasts for 1024 16MHz clock cycles in PAL TV mode (1016 cycles in NTSC or VGA modes). At the start of each line the CPU is taken offline by a BUSREQ signal for audio DMA. (There is short, variable delay of a few cycles following a Bus Request whilst waiting for an acknowledgment from the CPU). Once the audio system is online, it lasts around 20 clock cycles. Following on, the LineCop has control of the main system bus for as long as the necessary to complete the LineCop operations required on that line. Afterwards, the CPU continues normally (as long as it not forced to wait by it accessing video or sprite memory during active display lines).

Scanline Timing:

Bitmap and sprite video data is fetched simultaneously and concurrently with the CPU running normally as the three systems have their own memory buses. The time each system requires to build its internal buffer is variable and depends on the amount of data on a particular scan line. As mentioned, the CPU only has to wait if it tries to access bitmap or sprite memory whilst data is being fetched by the relevant system.

The blitter and linedraw systems are also forced to wait during the bitmap fetch part of a scan line. These systems have priority over the CPU in accessing video memory when its free (not being read by the video system) and force the CPU to wait if the CPU is trying access bitmap video memory at the same time. Active blits are paused at the “last 16 cycles” point, ensuring the CPU is not waiting at the start of a scanline (which could cause complications with the DMA functions). A paused blit continues after the bitmap layer data fetch period.

Video output:

⁸⁾ This is a non-standard mode and may not work on all VGA monitors.

Notes

• The Video Registers are located between $0200-$07ff in Z80 address space, unless paged out using the port: sys_alt_write_page
• All video registers are WRITE ONLY.

“vreg_xhws” - Horizontal Hardware Scroll (No effect in Chunky mode)

“vreg_vidctrl” - Playfield Control

Certain bits of this register take on different meanings depending on the video mode:

In Bitmap Mode (IE: When bit 0 is clear):

In Legacy Tile Map Mode (IE: When bit 0 is set and bit 0 of vreg_ext_vidctrl is clear):

In Extended Tile Map Mode (IE: When bit 0 is set, and bit 0 of vreg_ext_vidctrl is set):

“vreg_window_size” - Display Window Size - Sets size/position of display window.

When Reg_Switch is zero (bit 2 of vreg_rasthi is 0):

When Reg_Switch is one (bit 2 of vreg_rasthi is 1):

“vreg_yhws_bplcount” - Vertical Hardware Scroll Settings / Bitplane count

In Tilemap mode this register sets two separate hardware scroll values, one for each playfield. To set the scroll value for playfield 0, write to this register with bit 7 clear. To set the scroll value for playfield 1, write to this register with bit 7 set.

In Planar Bitmap Mode this register sets the number of bitplanes in the display:

In Chunky Bitmap mode this register sets the width of the pixels:

“vreg_rasthi” - Raster IRQ MSB, enable, clear & Window XY switch

⁹⁾ When this register is written with bit 7 set, the video IRQ flag is cleared and the rest of the register's contents are unchanged.

“vreg_rastlo” - Raster IRQ line position

Notes

• The counter used in the line comparison starts 16 lines above the first visible scanline (same as the sprites). Note: PAL, NTSC and VGA have different numbers of scanlines and no interrupt will occur if this register and the MSB in vreg_rasthi are set to a line the display mode never reaches.
• Please use a value above zero. Setting the raster IRQ line to 0 (including the MSB in vreg_rasthi) currently causes undesired effects (multiple interrupts) due to internal counter limitations.

“vreg_vidpage” - Video Page Access Control

This register selects which 8KB page of Video RAM appears in the Video RAM Access Window in Z80 address space (default location Z80 $2000-$3FFF). It also determines which 4KB of sprite RAM is to accept writes through the Sprite RAM access window (at Z80 $1000-$1fff).

When the register is written with bit 7 clear: Function is “set video page”.

(When Direct VRAM Write mode is active, bits 5:3 select the 64KB bank.)

When the register is written with bit 7 set: Function is “Set sprite page”.

(Note: Sprite RAM is write only)

Remember, the video and sprite access windows must be enabled with the port sys_mem_select for data to be transferred from the relevant RAMs.

“vreg_sprctrl” - Sprite Control

¹⁰⁾ These modes force the upper bits of individual sprite height control registers to be reassigned, see the sprite description text above for details.

¹¹⁾ Sprite Register Bank select bit:

“mult_write” - 16 bit multiplier

The signed word written here is multiplied by the word in the multiply table indexed by the following register. 16 bits (29:14) from the resulting 32-bit word are read from “mult_read” (the set of bits was chosen to provide fast scaling.)

“mult_index” - Maths table index (byte)

Selects which word from the look up table is used for the multiplication.

“linedraw_colour” - Line draw colour

Colour table index for line draw hardware. (There is only a single colour register, so to maintain a constant line colour, this value should not be changed whilst a line is being drawn.)

“vreg_ext_vidctrl” - Extended Video Mode Control Bits

“linecop_addr0”- LineCop list address bits 7:1 (bit = enable)

“linecop_addr1”- LineCop list address bits 15:8

“linecop_addr2” - Linecop list address bits 18:16

“vreg_palette_ctrl”- Palette Control

This register allows independent access to two palette control bits: The “live” palette (ie: that currently being used by the video hardware to fetch the colours) and the palette which receives CPU / LineCop writes. So that each setting can be changed independently (without reads) the register uses a bit (1) to select which register is to be accessed and a bit (0) for the data to be written:

Note: Changes to the live palette selection take effect at the start of the next scanline, whereas changes to the target palette register take effect immediately.

Blitter set-up

“blit_src_loc” - Source Address in VRAM Low 16 bits (little endian)

“blit_dst_loc” - Destination Address in VRAM Low 16 bits (little endian)

“blit_src_mod” - Source modulo [bits 7:0] ¹²⁾

“blit_dst_mod” - Destination modulo [bits 7:0] ¹²⁾

“blit_height” - Number of lines in blit - 1

“blit_width” - Width of blit in bytes - 1 [Write starts the blit]

“blit_misc” - Misc bits, see assignments below:

“blit_src_msb” - 2:0 highest three bits [18:16] of source address ¹³⁾

“blit_dst_msb” - 2:0 highest three bits [18:16] of destination address ¹³⁾

¹³⁾ Bit 16 is internally OR'd with the equivalent bit in “blit_misc”, this is for backwards compatibility. If you are only accessing video addresses < 128KB you can just use the “blit_misc” and ignore these two registers. Conversely if you are generally using the entire VRAM range its best to use these registers and write the MSB bits in “blit_misc” with zeroes.

Writing to “blit_width” actually starts the blit operation. Remember, the height and width values should be the blit dimensions less one.

Blitter Notes

Following a blit, all the registers except “Width” (which has to be re-written anyway) retain the values originally written to them. Most of the blitter registers can be changed once a blit is underway without problems, however the Modulos, Width and Misc registers should not be updated until a blit is finished.

Be wary when leaving the blitter running and returning to other code – this is of course perfectly fine as long as the other code does not go on to access the blitter's registers before it has finished a blit. The blitter status flag (bit 4 in sys_vreg_read) should be examined at relevant points to prevent clashing blitter ops.

¹²⁾ The modulo is the number of bytes added to the end of the source and destination counters at the end of each line. The polarity of these values is reversed by the blit direction. So if in descending mode, a negative modulo will result in a positive offset.

Line Draw

The line draw system uses registers in the range: $220-$23f. There are two main groups of registers: Control registers that need to be set up for each line, and an overall look-up table that only needs to be set up once on initialization.

The following four control words need to be set up for each line (each is 16 bits long):

linedraw_reg0 - Bresenham register [0]: 2x(dy-dx) [or 2x(dx-dy) ¹⁴⁾]

linedraw_reg1 - Bresenham register [1]: 2x(dy) [or 2x(dx) ¹⁴⁾]

linedraw_reg2 - Start location address of line in VRAM (bits 15:0)

linedraw_reg3 - Composite word, bits assigned as follows:

¹⁴⁾

1. Registers should be written with positive values, the sign of the value is held in the octant code.

1. If bit 14 of the composite word is set (because dy ⇒ dx) then the Bresenham decision [0] register should be loaded with 2 x (dx - dy) and decision register [1] should be loaded with 2 x (dx)

Writing to (the LSB of) this register actually starts the line drawing operation, so the sys_vreg_read should be checked beforehand.

In the above, “dy” and “dx” refer to delta_x and delta_y (IE: y1-y0, x1-x0)

The following four 16 bit registers register addresses have the same function as registers $220-$227 above, but they can hold different values. Having two sets of line-draw registers allows one set to be loaded whilst a previous line draw operation is still running. (The line_draw busy flag in vreg_read only needs to be checked before writing to the LSB of linedraw_reg3 (or linedraw_reg7) which starts the linedraw, or the linedraw_colour register, if changing colour.

linedraw_reg4 - Same function as $220/1 for register set 2

linedraw_reg5 - Same function as $222/3 for register set 2

linedraw_reg6 - Same function as $224/5 for register set 2

linedraw_reg7 - Same function as $226/7 for register set 2

The following eight 16 bit registers form a look-up table which is used by the internal harware to offset the plot address of each pixel. These registers need only be set once as part of an initialization routine, IE: not per line.

linedraw_lut0 - Pixel offset constant 0 .. (65536-Window width)+1

linedraw_lut1 - Pixel offset constant 1 .. (65536-Window width)-1

linedraw_lut2 - Pixel offset constant 2 .. Window width + 1

linedraw_lut3 - Pixel offset constant 3 .. Window width - 1

linedraw_lut4 - Pixel offset constant 4 .. 1

linedraw_lut5 - Pixel offset constant 5 .. 65535

linedraw_lut6 - Pixel offset constant 6 .. (65536 - Window width)

linedraw_lut7 - Pixel offset constant 7 .. Window width

(See also: Line colour register $20B - linedraw_colour)

Bitplane location

bitplane0a_loc (BPl register set A)

bitplane1a_loc (BPl register set A)

bitplane2a_loc (BPl register set A)

bitplane3a_loc (BPl register set A)

bitplane4a_loc (BPl register set A)

bitplane5a_loc (BPl register set A)

bitplane6a_loc (BPl register set A)

bitplane7a_loc (BPl register set A)

As above for Bitplane location register set B. Bit 5 of “vreg_vidctrl” controls which set is used by the hardware to build the display.

Each bitplane location “register” is 4 bytes long, the data required for each is:

Offset:  Data:
------------------------------------------------
+ 0   =  Location of Bitplane in video RAM [7:0]
+ 1   =  Location of Bitplane in video RAM [15:8]
+ 2   =  Location of Bitplane in video RAM [18:16]
+ 3   =  Reset internal offset counter / Set Modulo - see notes below

Notes

• The value written to the bitplane location registers only needs to be set once, an internal offset counter is added to the address as the frame is built up. There is only one offset counter which acts on all the bitplanes - it can be reset to zero by writing to the 4th byte of the even-numbered bitplane pointers (eg: bitplane0a_loc+3) this actually takes effect at the start of the next scanline.

• In chunky pixel mode, there is only one data-fetch start address, that is: bitplane0a/b

The modulo register holds the number of words to skip at the right of each scanline (positive only). This allows a window from within a larger image to be displayed (EG: can be used for scrolling and skipping lines in interlaced displays). There is one modulo register, it is located at the 4th byte of the odd-numbered bitplane registers (EG: bitplane1a+3) - as mentioned, the granularity is 2 bytes so for example a written value of 1 skips 2 bytes each line. The value in this register is internally latched at the start of each scanline and because of the way it is implemented there is an upper limit on the value it can hold (depends on the display mode) - values up to 192 (IE: skip 384 bytes) are OK. There is also a special case: If $FF is written to the modulo register the bitmap offset counter is reset at the start of each scanline, IE: With no other changes, the same line is used over and over.

Sprite priority mask (“priority_registers”)

Bit 0: bgnd colours 00-0F mask level 0, Bit 1: bgnd colours 00-0F mask level 1

Bit 0: bgnd colours 10-1F mask level 0, Bit 1: bgnd colours 10-1F mask level 1

Bit 0: bgnd colours 20-2F mask level 0, Bit 1: bgnd colours 20-2F mask level 1

Bit 0: bgnd colours 30-3F mask level 0, Bit 1: bgnd colours 30-3F mask level 1

Bit 0: bgnd colours 40-4F mask level 0, Bit 1: bgnd colours 40-4F mask level 1

Bit 0: bgnd colours 50-5F mask level 0, Bit 1: bgnd colours 50-5F mask level 1

Bit 0: bgnd colours 60-6F mask level 0, Bit 1: bgnd colours 60-6F mask level 1

Bit 0: bgnd colours 70-7F mask level 0, Bit 1: bgnd colours 70-7F mask level 1

Bit 0: bgnd colours 80-8F mask level 0, Bit 1: bgnd colours 80-8F mask level 1

Bit 0: bgnd colours 90-9F mask level 0, Bit 1: bgnd colours 90-9F mask level 1

Bit 0: bgnd colours A0-AF mask level 0, Bit 1: bgnd colours A0-AF mask level 1

Bit 0: bgnd colours B0-BF mask level 0, Bit 1: bgnd colours B0-BF mask level 1

Bit 0: bgnd colours C0-CF mask level 0, Bit 1: bgnd colours C0-CF mask level 1

Bit 0: bgnd colours D0-DF mask level 0, Bit 1: bgnd colours D0-DF mask level 1

Bit 0: bgnd colours E0-EF mask level 0, Bit 1: bgnd colours E0-EF mask level 1

Bit 0: bgnd colours F0-FF mask level 0, Bit 1: bgnd colours F0-FF mask level 1

“mult_table” WRITE ONLY

This table holds 256 signed 16 bit words. The entry selected by “mult_index” is multiplied by the signed word in “mult_write” and 16 bits [29:14] of the 32 bit result appears in “mult_read“

“vreg_read” - READ ONLY Status Register (Also available in port: sys_vreg_read)

¹⁵⁾ Remember, in VGA mode each scanline's data is output twice at double the normal frequency. This flag reflects the x-window of the normal PAL/NTSC ~15KHz scanline.

“mult_read” READ ONLY - Maths unit result (little endian):

Bits 29:14 from the longword result of the maths unit operation appear here.

OSCA locates a boot ROM at $0000-$01FF - this is contained within the FPGA config file. At reset, the ROM clears the following ports and video registers:

• sys_mem_select
  
• sys_alt_write_page
  
• sys_low_page
  
• sys_irq_enable
  
• sys_audio_enable
  
• sys_ps2_joy_control
  
• sys_vram_location
  
• sys_timer
  
• vreg_sprctrl
  
• palette (IE: background colour = $000)

All interrupts are disabled (IRQs via the Z80 DI instruction and NMIs via bit 0 of sys_hw_settings). The IRQ vector (at $0038) has the instruction “JP $0A00”, and the NMI vector (at $0066) has the instruction “JP $0A03”. OSCA is designed to use Interrupt Mode 1.

The ROM then attempts to load the main boot code from the onboard EEPROM. Two locations are checked:

EEPROM Block 0: $F000 [Primary bootcode location]
EEPROM Block 1: $F000 [Backup bootcode location]

To test for bootcode, a “databurst” command is sent to a PIC microcontroller which responds by sending 3520 bytes from the EEPROM. The ROM reads this data into system RAM $0200 onwards, checks the CRC checksum (held in the last two bytes) and executes it (with a JP $200) if the checksum is good.

(If the CRC doesn't match, the screen flashes magenta and the databurst is requested again from the backup. If this also fails, the screen goes grey indicating that a bootcode file should be downloaded via the serial link at 115KBPS. This grey screen condition can also be forced by holding up, right and fire on a joystick in Port 1 at power up. If at any point the screen flashes yellow, there was a time-out during the EEPROM databurst.)

It is possible to have read/write access the system RAM “underneath” the OSCA ROM/Palette at $000-$1ff (see the port ”sys_alt_write_page”). In all there are three options for this memory range:

A) Read ROM / Write palette (default)
B) Read system RAM / write palette (set by bit 4 of sys_alt_write_page)
C) Read System RAM / write system RAM (set by bit 6 of sys_alt_write_page)

The IRQ vectors must be set appropriately in system RAM when non-ROM reads are enabled (and interrupts are required).

(All ports are 8 bit unless stated)

($000-$6FF are write only registers)

¹⁶⁾ Same register location as below, set bit 7 for this function
¹⁷⁾ Same register location as above, reset bit 7 for this function