Accurate EGA/VGA emulation

[MrMadguy64]

Describe the bug

I think we need to create separate issue for this problem.

1. One byte is read/written by GC from/to all 4 planes at the same time at the same address during both CPU LATCH and CRTC LATCH (read only) cycles. Writing to some planes can be masked via Map Mask SC register. This register simply disables sending RAS signal to certain planes. I.e. nothing changes. Data is still written by GC to all 4 planes at the same time at the same address, but some planes are masked, i.e. don't respond to writing operations.
2. When Odd/Even mode is enabled in SC - CPU A0 bit controls, if even or odd planes are masked in addition to Map Mask register. When CPU A0 = 0, planes 1 and 3 are masked. When CPU A0 = 1, planes 0 and 2 are masked.
3. When Odd/Even mode is enabled in GC Mode register - it affects reading. When CPU read operation is performed, data is read from all 4 planes at the same time. But only one byte from one of GC controllers should be sent to CPU data bus! What data is actually sent to CPU - is controlled by GC read mode (either read or compare) and Read Map register. Bits 1 and 2 of Read Map are compared to Graphic Position register to determine, which GC should respond to read operation. Bit 0 is used to select even or odd plane. In byte mode Read Map register bit 0 decides, data from which plane should be sent to CPU. In Odd/Even mode it's replaced by CPU A0 bit. In this it's CPU, that decides, if data should be read from even plane or odd, not GC.
4. When Chain2 mode is enabled in GC Misc register, it affects CPU VRAM addressing. Please note. A0 that goes to SC/GC and A0 that goes to VRAM - are two different things! "Real" CPU A0 goes to SC and GC. I.e. one, taken from ISA slot. But what address actually goes to VRAM - is decided by Chain2 and Chain4 (in case of VGA) modes. Errr. Hard to explain it. CPU A0 is used to control, if even or odd planes should be read/written. But this task is accomplished by SC and GC via "masking" either even or odd planes. So, this A0 bit becomes unused for actual VRAM addressing. And as all VRAM read/write operations are always byte operations, it doesn't matter what this bit is used for - no word alignment is needed. When Chain2 mode is enabled - this VRAM A0 bit is replaced by either MOR PGSEL, CPU A16 or CPU A14 bit (if memory expansion is unavailable). I.e. it's used for Low/High page switching. It doesn't work this way in Chain4 mode. Page switching is unavailable in this case.
5. CRTC is used to produce VRAM address for reading data to be shown on screen. CRTC address - is separate address. It doesn't go through all logic described above. It's send directly to VRAM during CRTC LATCH cycles, while CPU address is send during CPU LATCH cycles. Therefore in order for CRTC addressing to match CPU addressing (A0 is replaced by PGSEL/A16), CRTC should be switched to WORD mode. This mode is interesting. As address is rotated left by 1 bit, 2 is added to address every character clock and A0 is replaced by A16 (former A15). What is interesting - is when Shift2 mode is enabled for 64Kb mode. In this case some "real" (CRTC's "real", not CPU's "real") A0 is also used. It's used to divide character clocks by 2. And BYTE PAN bit selects, if this bit is preset to 0 or 1 after previous HSYNC. Problem is - this bit doesn't seem to be exposed as explicit output. How SC odd/even cycles in Shift2 mode are kept in sync with value of this bit - is big mystery. Current guess - it's done via SYNC signal. SYNC - is equivalent of horizontal Display Enable (DE). SC seems to start from even cycle, when it receives this signal. Problem is - in order to keep CRTC in sync with it, DE skew should be set to 0 and BYTE PAN is set to 1 to compensate.
6. All things described above affect CPU read/writes and CPU/CRTC addressing only. But nothing above enables Odd/Even displaying mode. During CRTC LATCH mode GC reads data at CRTC address. But what GC reads - are always 4 bytes from all 4 planes. In case of VGA they're read into 32bit shift register. In case of EGA - it's 2x16bit shift registers. One into GC 1 for planes 0/1. Other into GC 2 for planes 2/3. I.e. 4bpp packed pixel isn't possible in case of EGA. Displaying mode is affected by one thing only - how data is shifted out. It's controlled by Shift2 GC bit. Overall idea - all 32 bits should be shifted out during one character clock. As 1 character clock = 8 pixels, then each pixel should be 4bpp (1bpp is emulated via setting all 4 bits to same value or via masking some planes in AC). If Shift2 is off - then 1 bit per pixel clock is shifted out from each plane. If Shift2 is on - two bits per pixel clock are shifted from each 0+1 (GC1) and 2+3 (GC2) pair. These planes are chained together.
7. 64Kb modes - are special case. They're 1bpp modes, i.e. 1 bit is shifted out every pixel clock. But they're Odd/Even modes, so planes 0+1 (GC 1) and 2+3 (GC 2) are chained to double VRAM address space size. This mode requires special bits to be set. Shift2 in SC and CRTC. SC sends Shift/Load signal to GC and CRTC address is updated every other character clock. Therefore all 16 bits are shifted out from GC every 2 character clocks, not 1. It's very simple. GC shift registers are 16bit ones. So it's possible to use them as one 16bit value instead of 2x8bit. But they shouldn't be reloaded every character clock then.
8. Text modes are special case. GC controls CPU reading/writing in this case, but not displaying. Displaying is performed by AC. And it has it's own hardcoded VRAM read logic. There are two CPU and CRTC addresses. Address A and address B. Address A is for planes 0/1 and address B is for planes 2/3. In case of CPU reading/writing and in Graphic mode they're exactly the same. But AC reading is different. Data reading has two stages. First character code is read at CRTC address A and stored along with row counter in special intermediate latch to form character generator address. Then this address is transferred to CRTC address B. Then AC reads attribute from address A and character generator data from address B.

As you might guess, 8bpp mode in VGA is implemented similarly to how CGA 2bpp mode is implemented in EGA. Only differences:

1. There is no Chain4 bit in GC, so, I guess, Chain4 bit in SC (despite of description) sets this mode for both reading and writing. Same as Chain2, but two LSBs are used for switching between planes instead of one.
2. GC has Shift256 mode (aka Shift4). 4 bits are shifted out from whole 32bit shift register every pixel clock.
3. SC has Shift4 mode. S/L is sent to GC every 4th character clock.
4. CRTC has DWORD and DIV4 (aka Shift4) modes. Address is updated every 4th character clock. Unfortunately on standard VGA VRAM size isn't quadrupled. Only 64Kb of VRAM are available in DWORD mode. 3rd party cards can do it.
5. AC has 256 color mode, that chains two 4bpp pixels together into 8bpp one. Disabling it should allow 4bpp packed pixel mode.

Funny thing. I haven't realized it before. But there are Shift4 modes in SC and CRTC, that aren't actually used anywhere. For now I don't know any useful implication for them, except may be some sort of 1bpp Chain4 mode.

Extra info about addressing:

1. Memory is 4x64Kb planes (Can be 16, 32, 48 in case of EGA). 1 byte is always read/written from/to each plane at exactly the same address - either CPU address or CRTC address. It can be seen as 65536 DWORDs.
2. In BYTE mode they're addressed linearly.
3. In Odd/Even SC/GC mode VRAM A0 is replaced by either PGSEL, A14 or A16. In WORD CRTC mode address is rotated left by 1 bit (i.e. multiplied by 2) and A0 is replaced by A15, so A15 selects either low or high page. In this case even DWORDs contain low page and odd DWORDs contain high page.
4. In Chain4 SG/GC mode A0 = A14 and A1 = A15. In DWORD CRTC mode address is shifted left by 2 bits (i.e. multiplied by 4) and A0 = A12 and A1 = A13. Data is stored in every 4th DWORD. There are 4 pages, 16Kb each. Data is stored in first DWORD in first page, in second DWORD in second page, in third DWORD in third page, in fourth DWORD in fourth page. No page selection available.
5. Note difference between CPU and CRTC addressing. CPU uses "real" address and CRTC address is set such way, as if it would be shifted right by 1 bit in WORD mode or by 2 bit in DWORD mode. It's done to save bits. It affects CRTC Start Address register.
6. Note, that A13/A14 substitution happens after shifting.

Steps to reproduce the behaviour

Blank

Expected behavior

No response

What operating system(s) this bug have occurred on?

Any

What version(s) of DOSBox-X have this bug?

Any

Used configuration

Output log

Additional information

No response

Have you checked that no similar bug report(s) exist?

• I have searched and didn't find any similar bug report.

Code of Conduct & Contributing Guidelines

• I agree to follow the code of conduct and the contributing guidelines.

[MrMadguy64]

Some tests, that should work on real hardware:

1. Odd/Even SC/GC rendering, BYTE CRTC displaying. PGSEL test. All 8 colors should be seen. Works in QEMU and 86Box, except high page. It's blank for QEMU and contains garbage data in 86Box.

title TestOE
.8086
.model tiny
jumps
.code
org 100h
Start:
	;Set mode
	mov ax, 13h
	int 10h
	;Graphic controller - enable Odd/Even addressing
	mov dx, 3CEh
	mov al, 06h
	out dx, al
	inc dx
	in al, dx
	or al, 02h
	out dx, al
	;CRTC - disable Chain4 and Odd/Even
	mov dx, 3D4h
	mov al, 14h
	out dx, al
	inc dx
	in al, dx
	and al, 0BFh
	out dx, al
	dec dx
	mov al, 17h
	out dx, al
	inc dx
	in al, dx
	or al, 40h
	out dx, al
	;Sequencer: disable Chain4, enable Odd/Even	
	mov dx, 3C4h
	mov al, 04h
	out dx, al
	inc dx
	in al, dx
	and al, 0F3h
	out dx, al
	;Prepare to write map mask
	dec dx
	mov al, 02h
	out dx, al
	inc dx
	;Prepare memory
	mov ax, 0A000h
	mov es, ax
	cld
	;Write even planes, low page - blue and green
	mov al, 03h
	out dx, al
	mov cx, 8000
	xor di, di
	mov ax, 0201h
	rep stosw
	;Write odd planes, low page - red and gray
	mov al, 0Ch
	out dx, al
	mov cx, 8000
	xor di, di
	mov ax, 0704h
	rep stosw
	;Prepare to write to high page
	mov dx, 3CCh
	in al, dx
	mov dx, 3C2h
	and al, 0DFh
	out dx, al
	mov dx, 3C5h
	;Write even planes, high page - light blue and light green
	mov al, 03h
	out dx, al
	mov cx, 8000
	xor di, di
	mov ax, 0A09h
	rep stosw
	;Write odd planes, high page - ligh red and white
	mov al, 0Ch
	out dx, al
	mov cx, 8000
	xor di, di
	mov ax, 0F0Ch
	rep stosw	
	;Pause, press any key to continue
	xor ax, ax
	int 16h
	;Return to text mode
	mov ax, 03h
	int 10h
	;Terminte
	ret
end Start

2. Odd/Even SC/GC rendering, BYTE CRTC displaying. 128Kb mode test. All 8 colors should be seen. Works in QEMU and 86Box, except high page. It's blank for QEMU and contains garbage data in 86Box.

title TestOE
.8086
.model tiny
jumps
.code
org 100h
Start:
	;Set mode
	mov ax, 13h
	int 10h
	;Graphic controller - enable Odd/Even addressing, set 128Kb mode
	mov dx, 3CEh
	mov al, 06h
	out dx, al
	inc dx
	in al, dx
	and al, 0F3h
	or al, 02h
	out dx, al
	;CRTC - disable Chain4 and Odd/Even
	mov dx, 3D4h
	mov al, 14h
	out dx, al
	inc dx
	in al, dx
	and al, 0BFh
	out dx, al
	dec dx
	mov al, 17h
	out dx, al
	inc dx
	in al, dx
	or al, 40h
	out dx, al
	;Sequencer: disable Chain4, enable Odd/Even	
	mov dx, 3C4h
	mov al, 04h
	out dx, al
	inc dx
	in al, dx
	and al, 0F3h
	out dx, al
	;Prepare to write map mask
	dec dx
	mov al, 02h
	out dx, al
	inc dx
	;Prepare memory
	mov ax, 0A000h
	mov es, ax
	cld
	;Write even planes, low page - blue and green
	mov al, 03h
	out dx, al
	mov cx, 8000
	xor di, di
	mov ax, 0201h
	rep stosw
	;Write odd planes, low page - red and gray
	mov al, 0Ch
	out dx, al
	mov cx, 8000
	xor di, di
	mov ax, 0704h
	rep stosw
	;Prepare to write to high page
	mov ax, 0B000h
	mov es, ax
	;Write even planes, high page - light blue and light green
	mov al, 03h
	out dx, al
	mov cx, 8000
	xor di, di
	mov ax, 0A09h
	rep stosw
	;Write odd planes, high page - ligh red and white
	mov al, 0Ch
	out dx, al
	mov cx, 8000
	xor di, di
	mov ax, 0F0Ch
	rep stosw	
	;Pause, press any key to continue
	xor ax, ax
	int 16h
	;Return to text mode
	mov ax, 03h
	int 10h
	;Terminte
	ret
end Start

3. Odd/Even SC/GC rendering, DWORD CRTC displaying. All 4 colors should be seen. Works in QEMU and 86Box.

title TestOE
.8086
.model tiny
jumps
.code
org 100h
Start:
	;Set mode
	mov ax, 13h
	int 10h
	;Graphic controller - enable Odd/Even addressing
	mov dx, 3CEh
	mov al, 06h
	out dx, al
	inc dx
	in al, dx
	or al, 02h
	out dx, al
	;Sequencer: disable Chain4, enable Odd/Even	
	mov dx, 3C4h
	mov al, 04h
	out dx, al
	inc dx
	in al, dx
	and al, 0F3h
	out dx, al
	;Prepare to write map mask
	dec dx
	mov al, 02h
	out dx, al
	inc dx
	;Prepare memory
	mov ax, 0A000h
	mov es, ax
	cld
	;Write even planes, low page - blue and green
	mov al, 03h
	out dx, al
	mov cx, 16000
	xor di, di
a:
	mov ax, 0201h
	stosw
	add di, 2
	loop a
	;Write odd planes, low page - red and gray
	mov al, 0Ch
	out dx, al
	mov cx, 16000
	xor di, di
b:
	mov ax, 0704h
	stosw
	add di, 2
	loop b	
	;Pause, press any key to continue
	xor ax, ax
	int 16h
	;Return to text mode
	mov ax, 03h
	int 10h
	;Terminte
	ret
end Start

4. 1bpp Chain4 mode test. Both line patterns should be the same. Doesn't work in QEMU, but all of a sudden works in 86Box.

title TestS4
.8086
.model tiny
jumps
.code
org 100h
Start:
	;640x200x4
	mov ax, 000Eh
	int 10h
	;Render
	call Render
	;Pause, press any key to continue
	xor ax, ax
	int 16h
	;320x200x8
	mov ax, 0013h
	int 10h
	;Enable SC Shift4
	mov dx, 3C4h
	mov al, 01h
	out dx, al
	inc dx
	in al, dx
	or al, 10h
	out dx, al
	;Disable GC Shift4
	mov dx, 3CEh
	mov al, 05h
	out dx, al
	inc dx
	in al, dx
	and al, 0BFh
	out dx, al
	;Enable CRTC Shift4
	mov dx, 3D4h
	mov al, 14h
	out dx, al
	inc dx
	in al, dx
	or al, 20h
	out dx, al
	;Offset = 640 / (8 * 4 * 2) = 10
	dec dx
	mov ax, 0A13h
	out dx, ax
	;Render
	call Render
	;Pause, press any key to continue
	xor ax, ax
	int 16h
	;Return to text mode
	mov ax, 03h
	int 10h
	;Terminte
	ret
Render proc
	;Disable planes 1-3
	mov dx, 3DAh
	in al, dx
	mov dx, 3C0h
	mov ax, 0112h
	out dx, al
	mov al, ah
	out dx, al
	mov al, 20h
	out dx, al
	mov dx, 3DAh
	in al, dx
	;Draw vertial line pattern
	mov ax, 0A000h
	mov es, ax
	xor di, di
	cld
	mov cx, 10 * 200
@@a:
	mov ax, 0201h
	stosw
	mov ax, 0804h
	stosw
	mov ax, 2010h
	stosw
	mov ax, 8040h
	stosw
	loop @@a
	ret
endp
end Start

[joncampbell123]

How do you compile this assembly into executable code? The ASM looks Microsoft MASM-ish.

Do you mind if I copy this ASM into test programs in the DOSLIB project that can compile to executable code you can run on both emulators and real hardware? I will make sure to put a README.TXT and a notice at the top of the .ASM listing this issue and the author as the origin of the source code.

[joncampbell123]

For reference, here's something I wrote in back in the 1990s when I was still learning assembly language. It hooks INT 10h and overrides the VGA text mode font. For fun, of course. https://github.com/joncampbell123/fontgdi2/

When I initially wrote it in 1996, I had an old Tseng ET4000 card that apparently didn't require me to switch off odd/even mode to write the FONT data. Then later on I pulled out the code, tried it on newer PC hardware, and I got the same artifacts as your project until the register values were updated to work properly again.

ET4000 cards are quite compatible with VGA but they do have a few nonstandard quirks about them, including how chained 256-color mode is mapped to planar memory. The DOSBox-X source code has plenty of remarks about ET4000 differences from standard VGA.

[MrMadguy64]

How do you compile this assembly into executable code? The ASM looks Microsoft MASM-ish.

Do you mind if I copy this ASM into test programs in the DOSLIB project that can compile to executable code you can run on both emulators and real hardware? I will make sure to put a README.TXT and a notice at the top of the .ASM listing this issue and the author as the origin of the source code.

It's TASM. Should be MASM-compatible, I guess. Code can either be compiled manually or via makefiles ("makefile" without extension, use "make" to launch it) like this:

NAME = TestOE
COM = $(NAME).com
OBJS = $(NAME).obj

!if $d(DEBUG)
TASMDEBUG=/la /zi
LINKDEBUG=/Tdc /v
!else
TASMDEBUG=/la
LINKDEBUG=/Tdc
!endif

$(COM): $(OBJS)    
	tlink $(LINKDEBUG) $(OBJS),$&.com

.asm.obj:
	tasm  $(TASMDEBUG) $&.asm

Please note. It's two-way thing. Some things are still theoretical. I'm almost sure, that things should work this way, but I haven't tested them on real hardware. And as code isn't tested on real hardware, it can also be buggy. So, I provide theoretical knowledge. But somebody should provide practical one. If code will work - then great! If it won't - I'll search for possible mistakes. If there wouldn't be any mistakes, then it's possible, that some VGAs (especially 3rd party ones) aren't 100% EGA compatible.

[joncampbell123]

Theoretical or not, it can help confirm emulation accuracy against current hardware. Much of the code in DOSLIB was written to play with hardware, both real hardware and DOSBox/DOSBox-X. Many findings from DOSLIB and real hardware were used to improve the emulation in DOSBox-X, especially Sound Blaster, GUS, and VGA/SVGA emulation.