Harlequin & Harlequin Plus hardware information

[mark_k]

Harlequin and Harlequin Plus information
----------------------------------------

2015-04-22  First version of this document


The Harlequin and Harlequin Plus are Zorro II frame buffer cards. See
  http://amiga.resource.cx/exp/harlequin
  http://amiga.resource.cx/exp/harlequinplus

This information should be enough to allow support for Harlequin (and possibly
Harlequin Plus) to be added to emulators, or for hardware-hitting programs to
be written. Directly accessing the hardware should allow significantly better
performance than going via harlequin.library.

Some possibilities:
 - Write an EVD (external video driver) for the ShapeShifter Mac emulator.
 - Write a device driver to use Harlequin RAM as a RAM disk, if you don't need
   to use its video output. That could allow up to 4MB per card without using
   any fast RAM.

This information was deduced from examining the code of harlequin.library
version 11.07. I would like to obtain any earlier or later library versions
for comparison.

Zorro II manufacturer/product numbers (decimal):
  Harlequin PAL        2118/100
  Harlequin NTSC       2118/101
  Harlequin Plus PAL   2118/102
  Harlequin Plus NTSC  2118/103

The Zorro II board size is almost certainly 128KB.

The Harlequin was available with several different RAM capacities:
  Harlequin 1500: 1.5MB, single RGB frame buffer
  Harlequin 2000: 2MB, single RGBA frame buffer
  Harlequin 3000: 3MB, two RGB frame buffers
  Harlequin 4000: 4MB, two RGBA frame buffers

The Harlequin Plus was apparently only available in 2MB and 4MB versions.

Three resolutions (video modes) are supported:
  PAL boards:  740x576, 832x576, 910x576
  NTSC boards: 740x486, 832x486, 910x486

910 pixels was probably chosen as the highest resolution because it is the
largest that fits into 2MB: 910x576x4 = 2096640 = 2MB - 512 bytes.

For NTSC, 910x486x4 = 1769040 = 2MB - 328112 bytes, so there is always some
wasted/spare RAM.



Register description
--------------------

  Offset        Description
  0.W     R/W   Configuration register
                Bit 15: 0 if genlock is fitted, else 1 (read only)
                Bit 14: Selects which buffer is displayed. 0 = 1st, 1 = 2nd
                        The change may not occur until the next vertical
                        blanking period.
                Bits [13:8]: Selects which 64KB bank from the (up to 4MB) on-
                        board RAM appears at offset $10000. [So bit 13
                        determines which buffer the selected bank is from.]
                Bit 7: 1 = Red channel enabled
                Bit 6: 1 = Green channel enabled
                Bit 5: 1 = Blue channel enabled
                Bit 4: 1 = Alpha channel enabled
                Bit 3: 0 = non-interlaced, 1 = interlaced
                Bit 2: 1 = Genlock enabled
                Bits [1:0]: Video mode select. 00 = 910, 01 = 832, 10 = 740

  $10000-$1FFFF The selected 64KB RAM bank appears here



Additional Harlequin Plus registers
-----------------------------------
  Offset        Description
  2.B     R/W   Interrupt control register
                Bit 7: IRQ. The interrupt handler should check this bit to
                        determine whether the interrupt is from this board.
                        The interrupt service routine should clear this bit.
                Bit 6: Interrupt enable, 1 = enable interrupts

  $11.B, $13.B, ..., $1D.B
                Brooktree Bt473 registers; see the Bt473 datasheet.



Harlequin Plus
--------------
Apparently the Harlequin Plus has a Brooktree Bt473 RAMDAC. So it must support
a paletted mode, but I'm not sure how that works. Are the pixel values only
taken from what are normally the "red" bytes in 24-bit mode? (Or only the
green bytes etc.) Or are pixels packed four-per-longword?

Harlequin Plus can cause level 2 interrupts, presumably for vertical blanking.
harlequin.library installs an interrupt handler and enables interrupts.

The Bt473 registers are accessed at odd bytes starting from board offset $11.
If one or more palette entries is to be changed, the harlequin.library
interrupt routine writes 256*3 bytes palette data to the RAMDAC like this:
 - Write 0 to Bt473 register 0 (board offset $11). That is the Bt473 address
   register (RAM write mode).
 - Loop writing the 768 bytes palette data (a byte at a time) to Bt473
   register 1 (board offset $13). That is the Bt473 colour palette RAM
   register.



RAM layout
----------
The frame buffer RAM is accessed in 64KB banks which appear at board offset
$10000. Each longword is of the form $rrggbbaa, where rr = red value,
gg = green, bb = blue, aa = alpha.

1.5MB and 3MB boards have no alpha channel RAM. Presumably bits [7:0] of each
longword read as open bus.

On 3MB and 4MB boards, memory for the second frame buffer is accessed by
setting the highest bank select bit (config register bit 13). On single frame
buffer (1.5MB and 2MB) boards, the non-existent memory of the second frame
buffer probably reads as open bus.

The RAM layout depends on the resolution used. For example, for 910-pixel
mode, one line of pixels occupies 910*4 = 3640 bytes. The first pixel of the
second line (assuming non-interlaced mode; see below) is at buffer offsets
3640-3643 and the first pixel of the third line is at offset 7280.

For 740-pixel mode each line occupies 740*4 = 2960 bytes, so the second and
third lines begin at buffer offsets 2960 and 5920 respectively.

In interlaced modes, two fields are stored sequentially in the frame buffer
memory. Numbering rows of the image from 0 to 485/575 (top to bottom), even-
numbered rows are read from the first, odd-numbered rows from the second.



Board features
--------------
The red, green, blue and alpha channels can be individually enabled and
disabled. Typically you might disable the RGB channels to blank the display
before writing to the frame buffer, then re-enable them afterwards.

When changing which buffer is displayed (configuration register but 14), after
writing a word (with bit 15=0) to the configuration register, the
harlequin.library code loops reading the configuration register until the
value AND $7FFF equals the value just written. So it's likely that bit 14 does
not change its state instantly. Perhaps the board hardware delays switching
the displayed buffer until the vertical blanking period.



Pixel clocks
------------
Harlequin supports three resolutions. From the manual:
             ------ PAL -----	----- NTSC -----
  mode  res  clock (Hz) ratio   clock (Hz) ratio
  00    910  17,500,000  1120   17,276,222  1098
  01    832  16,000,000  1024   15,797,201  1004
  10    740  14,250,000   912   14,066,432   894

"ratio" is the number of clock periods per scanline. The pixel clock is
doubled for non-interlaced modes. For NTSC boards, the actual/ideal clock
frequencies are expressed as rational numbers:
        res  clock
        910  4941/286 MHz
        832  4518/286 MHz = 2259/143 MHz
        740  4023/286 MHz



Pixel aspect ratios
-------------------
The de-facto standard square-pixel sampling rates for NTSC and PAL are
135/11 MHz and 14.75 MHz respectively. From that you can derive the Harlequin
pixel aspect ratios.

  Mode      Pixel clock    Pixel aspect		    harlequin.library aspect
            (interlaced)   ratio (X:Y)	            ratio (inverted)
  PAL
  740×576   14.25 MHz      59:57 = 1.03509 approx   192:185 = 1.03784 approx
  832×576   16 MHz         59:64 = 0.921875         12:13 = 0.92308 approx
  910×576   17.5 MHz       59:70 = 0.84286 approx   77:91 = 0.84615 approx
  NTSC
  910x486   4941/286 MHz   130:183 = 0.71038 approx
  832x486   4518/286 MHz   195:251 = 0.77689 approx
  740x486   4023/286 MHz   130:149 = 0.87248 approx

In harlequin.library 11.07 the hard-coded aspect ratio figures, which
HGetScreenInfo() puts in the xAspect and yAspect fields of the HScreenInfo
structure, are wrong for NTSC modes; it uses the same figures as for the PAL
modes. Also, the numbers seem to be backwards. For example it sets xAspect=91
and yAspect=77 for the 910x576 mode, whereas that should be 77 and 91.



Open questions
--------------
There are two 8KB EPROMs soldered directly to the daughterboard. I don't know
whether or not those contain Amiga code. The daughterboard connects to the
main board via a 24-pin connector; that may not have enough pins for the
required address and data lines.

harlequin.library 11.07 supports a couple of features of Harlequin Plus
boards: it enables vertical blanking interrupts and uses the interrupt routine
to write the Bt473 palette RAM if necessary.

The amiga.resource.cx page about the Harlequin Plus lists various features
which are not supported/used by harlequin.library. How many of these are
actually correct?
 - Are the possible horizontal resolutions 720, 768, 832, 910 pixels for PAL,
   and 640, 720, 832, 910 for NTSC?
 - What is "24 bit palette mapped colour"???
 - Does it support 15 bit graphics?
 - What are "8 bit direct" graphics?
 - Is it possible to store three 8-bit images in the framebuffer?
 - Can the alpha channel be reassigned to provide a 15 colour palette-mapped
   overlay?
 - How are vertical blanking interrupts specified to be either on the first
   or second interlaced fields?
 - Is the board RAM really "linearly mapped into the Zorro II address space"?

[Toni Wilen]

There are two 8KB EPROMs soldered directly to the daughterboard. I don't know whether or not those contain Amiga code. The daughterboard connects to the main board via a 24-pin connector; that may not have enough pins for the required address and data lines.

- No enough pins for all data and address lines
- If it uses some multiplexing, why would they bother with 2 ROMs?
- Why would they put ROMs in daughterboard if it needs to be accessed by Amiga's CPU.
- Assuming daughterboard is a genlock, main board probably works without it? ("Bit 15: 0 if genlock is fitted, else 1 (read only)")

Looks very much like RTG board (without any VGA chip) from emulation point of view, should not be that difficult to emulate. (minus genlock stuff, not going to bother with that)

EDIT: Forgot most important question: is there any (unique) software that uses/needs this board?

[mark_k]

Originally Posted by Toni Wilen

- No enough pins for all data and address lines
- If it uses some multiplexing, why would they bother with 2 ROMs?
- Why would they put ROMs in daughterboard if it needs to be accessed by Amiga's CPU.

That's what puzzles me. There isn't, as far as I can see from pictures, any CPU on the board so what are the EPROMs used for? I doubt anyone with real hardware (which includes me, though I forgot where I put my card...) would be willing to desolder and dump the EPROMs just to find out.

Originally Posted by Toni Wilen

- Assuming daughterboard is a genlock, main board probably works without it? ("Bit 15: 0 if genlock is fitted, else 1 (read only)")

The daughterboard isn't a genlock, but is probably related to genlock capability. A genlock can be attached externally to the upper 15-pin connector. From the user manual (see pages 64-66 of that PDF), the external hardware connects the /GPRES input to ground. That must be reflected in bit 15 of the config register.

The amiga.resource.cx Harlequin page has a pic of a genlock (which I think connects to the Amiga video slot) made by Satellite & Television, which connects to the Harlequin genlock port.

Looks very much like RTG board (without any VGA chip) from emulation point of view, should not be that difficult to emulate. (minus genlock stuff, not going to bother with that)

You could just ignore the genlock and alpha features. There's also a digital key output (corresponding to alpha bit 0), again that can be ignored. Some emulator infrastructure work might be needed because the Harlequin image would need to be in a separate window to the native Amiga display.

EDIT: Forgot most important question: is there any (unique) software that uses/needs this board?

Apart from the diagnostic/test program on the Harlequin disk?

Reading old magazine reviews of graphics packages could help answer that. There's a Real3D 1.4 support library on Aminet. There was a Harlequin version of TVPaint, a saver for ADPro. Perhaps there were similar savers for other packages like ImageFX, Imagine or Turbo Silver too?

[mark_k]

I read about the Harlequin Plus in some old magazine articles. That's probably where the amiga.resource.cx description came from. CU Amiga issue 25 March 1992 has a review starting on page 118.

I think it's most likely that products 101 and 103 supported by harlequin.library 11.07 are not actually the Harlequin Plus, but some intermediate hardware version which may not have been sold to the public.

Later versions of harlequin.library than 11.07 do exist; this image gallery at www.exec.pl shows a disk labelled Harlequin V11.09D. It would be nice to get hold of an image of that disk...

The MacroSystem Retina came with its own harlequin.library allowing compatibility with software written for the Harlequin. Any backwards-compatibility of the Harlequin Plus would probably have been done that way, rather than needing to be compatible at a hardware level.

About those EPROMs... look at the Impulse FireCracker-24 board. That's another dumb frame buffer card, and it actually has three 40-pin (so 16-bit-wide?) EPROMs. Two are socketed, labelled AUTO.NTSC and SYNC.NTSC, the other is soldered and labelled POINTER.NTSC.

Could the Harlequin EPROMs be related to generating fully-standard-compliant sync signals? They could contain lookup tables for sync generation or something???

[Toni Wilen]

It is possible EPROMs are used for generating multiple different sync signals. (http://www.google.com/patents/US4316219 does something similar)

EDIT: It probably uses this method because it does not have any true display (VGA) chip or chipset like "real" RTG boards use.

[gulliver]

Software that supported the Harlequin:

Spectra Paint
TVPaint < 3.5
ImageFX 2.0
Photogenics 1.2
Real3D 1.3
Caligari Broadcast
Sculpt 4D
AdPro
Imagemaster
Vistapro 3.0

Vidi-Amiga RT video digitiser

[gulliver]

The Kasmin was developed around the same time as the Harlequin and share a lot in development. It makes use of the "grafexa.library" which allows cards to share a common software interface.

Cardless Software
--------------------

A version of the Harlequin low level library is supplied that
will work without a Harlequin card fitted and simulate the
actual operations available with the card. The library is
located in the libs directory on the developers disk and
called harlequin_cardless.library, it will be necessary to
copy this file to your assigned libs: directory, as well as
the grafexa.library. The software simulates a double buffered
PAL card with alpha channels fitted.

When used with a standard A2000 and 68000 the library will
operate at approximately the same speed as an A2000 and
Harlequin card configuration. When used with an A2000 and
accelerator card or an A3000 the library will run faster than
normal, this is because the simulated writes will be to 32 bit
memory at full processor speed. It is unfortunately not
possible to give timings for how much of a speed increase this
will provide as it very much depends on the operation. The
only way to obtain accurate timings is to test with a card
fitted!

Attached you will find both harlequin_cardless.library and grafexa.library

[mark_k]

Thanks for that. harlequin_cardless.library in that archive is v12.3, as compared with 11.07 on the Harlequin disk from amiga.resource.cx.

grafexa.library attempts to open harlequin1.library, hplus.library, horizon.library, kasmin.library and harlequin_cardless.library.

All those libraries probably provide the same basic interface/functions as harlequin.library. I guess hplus.library is specifically for the Harlequin Plus.

I did find a page with some helpful/interesting files (including the source code to kasmin.library): http://www.ikvideo.co.uk/Kasmin/

Sadly no later harlequin.library or hplus.library there though.

Various features of the Harlequin Plus can be figured out from the Bt473 datasheet. However I'd really need to know the the CR3-CR0 control register bit connections in order to be certain about anything. (Two of them may connect to the chip S1 and S0 pins; the values on those pins would need to be changed in order to enable 8- or 15-bit mode for example.)

Maybe someone with an actual Harlequin Plus will read this thread eventually...

[Arnie]

I don't know if you already have this but i found an online manual for the Harlequin board.

https://www.yumpu.com/en/document/vi...dware-database

[Toni Wilen]

Originally Posted by Toni Wilen

Looks very much like RTG board (without any VGA chip) from emulation point of view, should not be that difficult to emulate. (minus genlock stuff, not going to bother with that)

It is like RTG but I missed one very important detail: it is not that useful unless you can also see chipset display at the same time. So emulation is not going to happen soon.

[Toni Wilen]

Old thread but lets add note that Harlequin emulation is now implemented.

Plus version only partially emulated, no software found that uses extra (mainly BT RAMDAC) features.