openMSX/doc/internal/vram-addressing.txt

VRAM Addressing
===============

This document describes a model for the way the V9938 VDP calculates
addresses in VRAM using base registers and indices.

General Formula
---------------

General formula for VRAM addressing:
  vram_address = index1 & mask
where:
  vram_address is the index in VRAM
  index1 is the index in the particular table, such as the name table or
    color table. The unused bits of index are all ones.
  mask is the value in the table's base register. The unused bits of mask
    are all ones.

Examples:

The name table base register is VDP R#2.
It contains A16-A10 of the mask, the other bits are 1.
If R#2 would contain 24h, the mask would be:
  (24h << 10) | ~(-1 << 10) = 093FFh

In SCREEN1 (Graphic 1) there are usually 24 lines of 32 characters each.
However, the actual screen height is 32 lines, as can be seen when the
vertical adjust register R#23 is used. So the number of characters per
screen is 32*32 = 1024 = 2^10. With one byte per character, the index is
10 bits wide.

If the index would be 157h, this is extended with leading ones for A10 and
higher (1FC00h) to become 1FD57h. Then the final address is:
  vram_address = 1FD57h & 093FFh = 09157h

Note that in this case, the final address is equal to:
  R#2 * 2^10 + index = 09000h + 157h = 09157h
This is true for all display modes in which the used bits in the base
register (A16..A10 in this case) do not overlap the bits in the index
(A9..A0 in this case). This is also the way application programmers
typically use the table base address registers.

In SCREEN5 (Graphic 4) there are 256 lines of 128 bytes each. Only 212 lines
are visible at a time, but using the vertical adjust register R#23 all 256
lines can be seen. A line is 256 pixels wide, with 4 bits per pixel that
makes 128 bytes per line. So the total number of bytes per screen is
256 * 128 = 32768 = 2^15. Therefore the index is 15 bits wide.

If the index would be 4521h, this is extended with leading ones for A16 and
A15 (18000h) to become 1C521h. Using the same mask as before (093FFh), the
final address is:
  vram_address = 1C521h & 093FFh = 08121h

Note that in this case, the final address is NOT equal to:
  R#2 * 2^10 + index = 09000h + 4521h = 0D521h
The VDP data book states that in SCREEN5 bit4 to bit0 should be 1, in those
cases the general formula is equivalent to addition. But when some of those
bits are zeroes, the general formula gives the same result the real VDP
does, while addition does not. The many-scrollers part of Anma's "Source of
Power" demo uses this feature to display the same scrolling text many times
on the same screen.

Range Checking
--------------

Different VDP subsystems are interested in different tables. For example,
the sprite subsystem is only interested in the sprite name and pattern
tables. On reads and writes to tables, interested subsystems must be
informed so they can update their internal state. Therefore an algorithm is
needed which calculates in which tables (if any) a given address is located.

Here is the address calculation formula again:
  vram_address = index1 & mask
The lowest address within the range is when the index is 0, index1 then
contains only ones in unused bits. The highest address (inclusive) is when
the index is all ones, then index1 is also all ones and the address is equal
to the mask. However, not all addresses between the lowest and the highest
address actually occur if the mask has one or more zeroes in the bits that
overlap with the index.

Let "inside : Int -> Bool" be the function that tells whether an address is
inside a table:
  inside.addr = (Exist i : i in Indices : i & mask = addr)
In English: there is an index i, for which the VRAM address is addr.

A convenient formula for the inside function is this one:
  inside.addr =
    addr & (~mask | (-1 << index_width)) = mask & (-1 << index_width)
Note that "addr" only occurs once and all other values are constant for each
display mode, so the check takes two operations (one compare and one AND).
This is probably the cheapest you can get.

Index Width
-----------

Which address bits are stored in the table base address registers is
documented in the VDP data book, but which address bits are produced by the
index is not documented there. This section fills that gap.

- Name Table -

Name table base address is [A16..A10] (R#2).

Display mode:   Index width in bits:
   Text 1         12 (*1)
   Text 2         12
 Multicolor       10 (*2)
  Graphic 1       10 (*2)
  Graphic 2       10 (*2)
  Graphic 3       10 (*2)
  Graphic 4       15
  Graphic 5       15
  Graphic 6       15 + plane (*3)
  Graphic 7       15 + plane (*3)
(*1) Text 1 index is calculated as 00C00h + position.
     On MSX1 it was 10 bits wide. For some reason, unifying address
     calculation with Text 2 must have been simpler than keeping it 10 bits
     wide, even though unification requires an add operation.
(*2) Maybe this is 12 bits and index = 00C00h + position just like Text 1.
     That's equivalent to 10 bits though, because there are 1024 characters
     per screen.
(*3) See "Planar Addressing" section for details.

- Pattern Table -

Pattern table base address is [A16..A11] (R#4).

Display mode:   Index width in bits:
   Text 1         11
   Text 2         11
 Multicolor       11
  Graphic 1       11
  Graphic 2       13
  Graphic 3       13
  Graphic 4       -
  Graphic 5       -
  Graphic 6       -
  Graphic 7       -

- Color Table -

Color table base address is [A16..A6] (R#3 and R#10).

Display mode:   Index width in bits:
   Text 1         -
   Text 2         9
 Multicolor       -
  Graphic 1       6 (*1)
  Graphic 2       13
  Graphic 3       13
  Graphic 4       -
  Graphic 5       -
  Graphic 6       -
  Graphic 7       -
(*1) Bit5 is fixed to zero.

- Sprite Attribute Table -

Sprite mode:    Index width in bits:
   mode 1         7
   mode 2         10 (*1)
(*1) Bit9 selects sprite color table (0) or sprite attribute table (1).
     Bit8 and Bit7 are fixed to zero for the attribute table.

- Sprite Pattern Table -

Sprite mode:    Index width in bits:
   mode 1         11
   mode 2         11

Index Calculation
-----------------

The following variables occur in every display mode:
  org_line: display line,
            0 <= org_line < 256
  line:     org_line after scroll adjustment (R#23 is applied),
            0 <= line < 256
  name:     value in VRAM at address (name_index & name_mask),
            0 <= name < 256

The "/" operation is integer division ("div").
The "%" operation is modulo/remainder ("mod").

- Text 1 -

Aka SCREEN0, WIDTH40.
0 <= x < 40
y = org_line / 8
name_index = 00C00h + y * 40 + x
pattern_index = name * 8 + line % 8

Adding 00C00h was probably done to make the index 12 bits wide, just like
in Text 2 mode. You can see this addition in action if you enable 212 lines
display and then play with different values of R#2. Pay attention to the
characters displayed in the lower few lines of the screen.

- Text 2 -

Aka SCREEN0, WIDTH80.
0 <= x < 80
y = org_line / 8
name_index = y * 80 + x
pattern_index = name * 8 + line % 8

- Multicolor -

Aka SCREEN3.
0 <= x < 32
y = line / 8
name_index = y * 32 + x
pattern_index = name * 8 + line % 4

- Graphic 1 -

Aka SCREEN1.
0 <= x < 32
y = line / 8
name_index = y * 32 + x
pattern_index = name * 8 + line % 8
color_index = name / 8

- Graphic 2 and 3 -

These modes are equivalent, except for the sprite mode.
Aka SCREEN2 and SCREEN4.
0 <= x < 32
y = line / 8
name_index = y * 32 + x
pattern_index = ((line / 64) * 256 + name) * 8 + line % 8
color_index = ((line / 64) * 256 + name) * 8 + line % 8

- Graphic 4 -

0 <= x < 256
name_index = line * 128 + x / 2

- Graphic 5 -

0 <= x < 512
name_index = line * 128 + x / 4

- Graphic 6 -

0 <= x < 512
name_index = line * 128 + x / 4
plane = (x / 2) % 2

- Graphic 7 -

0 <= x < 256
name_index = line * 128 + x / 2
plane = x % 2

- Sprite Mode 1 -

0 <= sprite_nr < 32
attrib_index = sprite_nr * 4

0 <= pattern_nr < 256
pattern_index = pattern_nr * 8

When sprite size is 16x16, Bit1 and Bit0 of the index are ignored.
Four patterns define the look of a single sprite, like this:
 0 2
 1 3

- Sprite Mode 2 -

0 <= sprite_nr < 32
attrib_index = 512 + sprite_nr * 4
color_index = sprite_nr * 16

0 <= pattern_nr < 256
pattern_index = pattern_nr * 8

When sprite size is 16x16, Bit1 and Bit0 of the index are ignored.
Four patterns define the look of a single sprite, like this:
 0 2
 1 3

Planar Addressing
-----------------

The V9938 has 3 pins that select a group of VRAM ICs each: CAS0, CAS1 and CASX.
CASX is used to select the expansion RAM, which can be accessed through the CPU
interface and through commands, but cannot be displayed directly.

Each VRAM group can be 0K, 16K or 64K. A group can consist of 8 chips of 1-bit
wide RAM or 2 chips of 4-bit wide RAM, but for the purpose of addressing we can
just pretend it is 1 chip with 8-bit wide RAM.

In real MSX machines, the following group combinations are used:

  CAS0:  CAS1:  CASX:   Description:
   16K     0K     0K    MSX1 with V9938 and 16K VRAM (*1)
   64K     0K     0K    MSX2 with 64K VRAM (*2)
   64K    64K     0K    MSX2 with 128K VRAM
   64K    64K    64K    MSX2 with 128K VRAM and 64K expansion (*3)

*1: Examples are the Spectravideo SVI-738 X'PRESS and the Yamaha CX5MII/128.
    The only V9938-specific display mode that they can fully display is
    80-columns text mode (TEXT2).
*2: Known 64K VRAM machines: Canon V-25, Hitachi MB-H3, Talent TPP-311 and 312,
    Toshiba HX-23.
*3: No known machines shipped with expansion VRAM. It was a popular amateur
    upgrade for users of FastCopy, to reduce the number of required disk swaps.

In most display modes addressing is linear, meaning the lower 64K of address
space uses the VRAM connected to CAS0 and the upper 64K of address space uses
the VRAM connected to CAS1.

In SCREEN7/8 (Graphic 6/7) the addressing is planar, meaning that even VRAM
addresses are mapped to CAS0 and odd addresses are mapped to CAS1. This means
that SCREEN 7/8 are only available on 128K VRAM machines. The most likely
reason for using planar addressing is getting a higher bandwidth: even though
the data lines are shared between all VRAM groups, the row select has to be
done only once.

VR=0 / VR=1 mode
----------------

The VDP chip has 10 pins that are connected to the VRAM subsystem to control
the read/write address. There are 8 address pins, these select the CAS/RAS
address. And there is a CAS0 and CAS1 pin, these select one of two ram chip
(groups). In total this allows for a 17-bit address space (=128kB). (I'm
ignoring the extended VRAM here).

When the VDP does a memory access, it's puts the 17-bit logical address on
these pins. The way how this is done depends on the VR bit (bit 3 of register
8), see table below.

In VR=1 mode, it first puts the bits A15-A8 on the address bus, followed by the
bits A7-A0. The whole time either pin CAS0 or CAS1 is selected, depending on
address bit A16. In VR=0 mode, .. well see table ;)


  VDP  |         VR=0         |         VR=1         |
address|----------------------|----------------------|
  pin  | RAS(high) | CAS(low) | RAS(high) | CAS(low) |
-------+-----------+----------|-----------+----------|
  AD0  |     A6  #2|     1  #1|     A8    |    A0    |
  AD1  |     A7    |    A0    |     A9    |    A1    |
  AD2  |     A8    |    A1    |    A10    |    A2    |
  AD3  |     A9    |    A2    |    A11    |    A3    |
  AD4  |    A10    |    A3    |    A12    |    A4    |
  AD5  |    A11    |    A4    |    A13    |    A5    |
  AD6  |    A12    |    A5    |    A14    |    A6    |
  AD7  |    A13    |    A6  #2|    A15    |    A7    |
-------+-----------+----------|-----------+----------|
CAS0/1 |          A14         |          A16         |

#1  this pin is always '1' in the CAS phase
#2  A6 is output both in CAS and RAS phase, this allows to use both 8/6 and 7/7
    RAS/CAS configurations (see VDP data sheet for details)


One important side-effect is that in VR=0 mode, the VDP can only address 32kB
memory. This is what makes the demo 'syntax infinity' work even though R14 is
programmed 'wrongly' (it writes to address 0x1????, but expects the data to end
up at address 0x0????).

Another side effect is that when switching between VR=0 and VR=1 modes, the
address space gets shuffled around, much like bit 7 in VDP register 1 for
TMS99x8 chips.