Test program list/requests (2018 December to 2019 Febrary)

Is your feature request related to a problem? Please describe. I'm going to slow development of DOSBox-X for a bit (leave it to bug fixes) and focus on developing DOS programs to run both within DOSBox-X and on real hardware as a way to validate that emulation is as accurate as possible.

You may remember in July 2018 when I wrote a program to run through the various INT 10h video modes to test that the modes acted as expected and that various basic tweaks to the VGA hardware acted as expected.

The idea is to do the same with other parts of the hardware, though not yet as comprehensive.

These test programs will exist for both IBM PC and NEC PC-98 platforms.

I have my own list to start with, anyone else here is welcome to suggest additional tests.

Some tests will be written to talk to hardware in the same manner as some games or programs are observed to do.

These tests will exist as executable DOS programs.

They will be written to run on real hardware and within DOSBox-X.

They will interact with a testing framework by returning pass or fail, ideally with output that can be written to a log file indicating what if anything went wrong.

If anyone wants to write or contribute test programs, they are welcome to do so.

Test cases not finished by the end of Feburary 2019 will be carried over to the next issue to be created for March 2019 to May 2019.

They will be expected to run:

In DOSBox-X, in the DOS environment provided by DOSBox-X
In DOSBox-X, in an MS-DOS environment loaded from a boot disk or hard disk image.
On real hardware, with a real MS-DOS environment.

Secondary testing, where the code may fail:

DOSBox SVN, in the DOS environment provided by DOSBox
DOSBox SVN, in an MS-DOS environment loaded from a boot disk or hard disk image.
Bochs
QEMU
VirtualBox

CPU test ideas, pure ASM code, to run just before BIOS POST at startup. Remember the function I added to load a blob of executable code in dosbox.conf just before BIOS POST?

ADD/ADC/SUB/SBB flags tests
INC and DEC do not modify carry as documented
SHL/SHR/SAR modify flags as expected including CF and OF behavior needed by some games (such as Appare-den sprite decompression/rendering)

Basic CPU tests listed above will be carefully confined to pre-boot environments since, if the instructions do not follow the basic behavior expected, neither will they behave properly when running through the C runtime of a typical EXE nor the DOS kernel.

Timer tests:

Timer 0 countdown tests, mode 2 and 3
Timer 0 can be used to track the passage of time (normal timer loop delay)
Timer 2 (PC speaker) can be used to track the passage of time (seen in a few 1993-ish Demoscene productions for IBM PC, i.e. muting the PC speaker but letting it cycle, so that music can use Timer 0) for IBM PC and possibly NEC PC-98 Timer 1 (PC speaker).
Timer 0 one-shot tests
Timer 2 (PC speaker on IBM PC) or Timer 1 (PC speaker on NEC PC-98) one-shot tests (Realsound digitized speech through PC speaker technique)
Timer 0 square wave monitor through Interrupt Request Register of master PIC on IBM PC and NEC PC-98 (Steel Gun Nyan)
Timer 2 (PC speaker) square wave monitor through port 6x? (don't recall exactly) on IBM PC
Timer 2 (PC speaker) start/stop cycling according to one of the bits in port 61h on IBM PC.
Timer 2 (PC speaker) can keep cycling but output is muted (gated) by the other bit in port 61h on IBM PC.
Timer 0 will always cycle even if IRQ 0 masked at PIC on IBM PC and NEC PC-98.
Timer 0 frequency is 1193182Hz on IBM PC, 1996800Hz on PC-98 (if 8MHz clock) or 2457600Hz on PC-98 (if 5/10MHz clock). The test will need to blink or flash something at a 1 second duty cycle with a seconds count on the screen, and ask the user to time that the test is a fixed amount of seconds long. The test might do additional measurements and compare against vertical retrace (if it can be determined), RTC clock interrupt (IRQ8 on IBM PC/AT), serial UART in loopback mode, PC-98 bus mouse interrupt, PC-98 retrace interrupt, etc. as reference as well.
Timer 0 is 1996800Hz if BIOS data area 0x501 bit 7 is set, 2457600Hz if clear on PC-98. This should be carried out in the same test program as the one above that measures against other sources.
Timer 0 is 1996800Hz if port 42h bit 5 is set, 2457600Hz if clear on PC-98. This should be carried out in the same test program as the one above that measures against other sources. This program will produce incorrect results on units with super high resolution displays where port 42h carries all printer status lines.
BIOS data area 0x501 bit 7 and port 42h bit 5 agree, or else there may be a problem, on PC-98.

Timer, PC-98 BIOS functions INT 1Ch:

IRQ0 is normally masked
INT 1Ch AH=02h (set interval timer) should cause IRQ0 to become unmasked, the timer reprogrammed to a specific interval, and IRQ0 to signal once per tick until the counter value in BIOS data area 0x58A is reduced to zero. IRQ0 should be masked again when the counter expires.
The fixed interval used by the BIOS should correspond to 1/100th of a second.
When the counter expires, the BIOS IRQ0 handler should execute INT 07h.
Hook INT 1Ch to confirm that the IRQ0 handler is calling INT 1Ch AH=3 (continue interval timer) per IRQ0 interrupt as normally expected by the PC-98 BIOS, except when the counter expires. Test is ONLY valid on PC-98 hardware. The use of direct calls to IO_ReadB and IO_WriteB makes this test impossible within DOSBox-X.
Hook IRQ0, chain to the BIOS, confirm that the BIOS decremented the counter and kept the timer unmasked on return from the BIOS interrupt handler. (more likely to work in DOSBox-X and on real hardware).

Timer test questions (not sure yet):

Timer 1 (PC speaker) does the timer stop cycling if you set inhibit bit in system 8255 (ports 31h-37h) on NEC PC-98, or does it just gate the output of the timer to silence the speaker?
Can you use Timer 0 in one-shot mode to trigger an interrupt after a specific delay? (IBM PC and NEC PC-98)
On the original IBM PC (5150), can Timer 1 (DRAM refresh) read back a countdown value on IBM PC?

Reminder to self:

IBM PC/AT INT 15h AH=86h "WAIT" call does not use Timer 0 to do a wait loop. It uses IRQ 8 (RTC clock interrupt) instead, and is therefore unrelated to the timer that this set is written to test.

Specific programs to use while testing:

Yksoft1 "Bad Apple" ASCII animation program (PC-98) which uses INT 1Ch timer interval.

A20 gate: For each test the 64KB memory region at the 1MB barrier (FFFF:0000) will be compared against the bottom of memory (0000:0000) to determine A20 status

Test enable/disable via XMS (HIMEM.SYS)
Test that HIMEM.SYS can return A20 status, at least when HIMEM.SYS is called on to enable/disable it.
Test enable/disable via keyboard controller at ports 60h/64h on IBM PC/AT
Test enable/disable via PS/2 system port 92h on IBM PC/AT
Test enable/disable via BIOS INT 15h on IBM PC/AT
Test that writing port F2h always unmasks A20 regardless of value or current status on NEC PC-98 (as documented)
Test enable/disable via port F6h on NEC PC-98 (writing 0x02 or 0x03)
Test that writing anything else (other than 0x02-0x03) to port F6h does not affect A20 gate on NEC PC-98

Less certain:

HIMEM.SYS A20 global enable/disable vs local enable/disable function tests

Mouse:

Test that INT 15h allows setting a callback function to receive PS/2 data on IBM PC, and that data comes in. Real hardware will require user to move the mouse as part of the test. Within DOSBox-X the integration device can be used to stuff PS/2 mouse data to itself. NOT CERTAIN: Whether this INT 15h call unmasks IRQ 12 or not.
Test that INT 33h can be used to read mouse position and button status on IBM PC and NEC PC-98. Real hardware and NEC PC-98 mode of DOSBox-X will require the user to move and interact with the mouse, IBM PC mode will use the DOSBox-X integration device to stuff PS/2 mouse input to itself.
Talking directly to ports 60h and 64h will allow reading keyboard input (IRQ1) and mouse input (IRQ12) without dropping interrupts on IBM PC. On real hardware the user will need to move the mouse and interact with the program. In DOSBox-X the integration device can be used to stuff PS/2 input to itself. Mouse interrupt and data should NOT occur unless moving the mouse or clicking buttons. On laptops, make sure the Synaptic touchpad is in PS/2 emulation mode (acts like PS/2 mouse) and not in it's native touchpad mode which will send a stream of data if the user's finger is on or over the touchpad. Make sure to initialize the mouse to disable scroll wheel data as well, which changes the packet format to a 4 byte format when enabled. The program is looking for the traditional 3-byte PS/2 data packet.
Talking directly to the bus mouse interface (I/O ports 7FD9-7FDF) and IRQ 13 on NEC PC-98 reads mouse motion and button input.
Regardless of mouse input, mouse interrupt IRQ 13 is periodic on NEC PC-98. Should default to 120Hz, writing values to I/O port BFDB should select between 120Hz, 60Hz, 30Hz, and 15Hz and interrupt signal should occur at those rates. Interrupt is expected to fire whether mouse input happens or not.
Mouse motion continues to accumulate until the bit is set on Port A of the bus mouse interface to clear counters on PC-98. Setting the bit should always clear the counters, not setting the bit should mean the count continues to accumulate (PC-98)

Test, not sure:

Bit 4 of port C of the bus mouse interface should gate the interrupt. It should not re-fire the interrupt when toggled, but it should prevent an interrupt if set. NEC PC-98 mode (Amaranth mouse behavior)
Is the periodic output of the mouse interface visible in the IRR register of the slave PIC, and does inhibiting it change what is visible from the IRR? (NEC PC-98)

Interrupt controller:

Masking an interrupt prevents it from happening (IBM PC and NEC PC-98)
A pending interrupt, masked, should appear on the IRR register of the PIC but not fire
A pending interrupt, not masked, but CPU cleared the interrupt flag, should appear on the IRR register of the PIC but not fire
An interrupt should appear in IRR, then move to the ISR (interrupt service register) when fired and CPU acknowledges interrupt.
Acknowledging the interrupt should clear the ISR bit.
The same interrupt should not happen again while the ISR bit is set.
Masking the cascade interrupt should prevent all slave PIC interrupts from working until unmasked.
An interrupt handler, before acknowledging the interrupt, should be able to read the ISR register and see it's own interrupt still in service. Acknowledging the interrupt should then read the ISR as not in service anymore.
The cascade interrupt should show as in-service if slave PIC interrupts interrupt the CPU, and the slave PIC ISR register should show which one is in service.
When an interrupt happens, and the CPU re-enables interrupts during the interrupt handler, only higher priority interrupts should occur. The same interrupt should not happen until acknowledged, and lower priority interrupts should never occur until the current interrupt is acknowledged.
The CPU should never execute an interrupt handler associated with the cascade interrupt itself. On IBM PC/AT, the interrupt associated with IRQ 2 should never happen (NOTE: the test will have to block IRQ 9 so the BIOS is not there to execute IRQ 2 for backwards compat during the test). On PC-98, the interrupt associated with IRQ 7 should never happen. Note that known 8259 behavior is to interrupt the CPU with the lowest prio IRQ (IRQ 7 on master, IRQ 15 on slave) if it goes to interrupt the CPU but the device withdraws the interrupt signal before the CPU acknowledges it. NOT SURE: If IRQ 7 is cascade, will the PIC still behave in that manner in that case and signal the interrupt for IRQ 7?
Changing the base IRQ number on the PIC should cause interrupts to occur from that base IRQ. Changing the base IRQ of the master PIC to 0x60 should cause IRQ1 to trigger INT 61h.

Not sure:

If the ISR bit is set, and the device fires the interrupt again, the IRR bit should become set but should not fire the interrupt until acknowledged (ISR is reset).
Slave PIC interrupts should not interrupt the CPU if the cascade interrupt on the master has not been acknowledged (ISR bit set). This means that if IRQ 10 is fired, IRQ 8 (higher priority) or any other slave interrupt cannot interrupt the CPU again until the cascade interrupt is acknowledged on the master, but higher priority interrupts on the master can interrupt. This is known on IBM PC, but the behavior of PC-98 games makes this unclear on NEC PC-98. The use of "buffered mode" on PC-98 may or may not be related.

Keyboard:

IBM PC/XT and Tandy: XT type keyboard handler to process input from the PPI (an 8255) via port 60h. Latch keyboard byte, process, then set up keyboard to enable another byte to come in. Verify IRQ1 happens. (Future DOSBox-X support to emulate PC/XT type keyboard)
IBM PC/XT verify that there is an 8255 at I/O ports 60h-63h (PPI), that it behaves as expected (ref: http://hackipedia.org/browse.cgi/Computer/Platform/PC%2c%20IBM%20compatible/Computers/IBM/PC/IBM%20Personal%20Computer%20Hardware%20Reference%20Library%20Technical%20Reference%20%281984%2d04%29%20Revised%20Edition%2epdf) and (ref: http://www.minuszerodegrees.net/5160/diff/5160_to_5150_8255.htm)
IBM PC/XT check whether I/O ports 60h-63h have alias ports 64h-7Fh (as real 5150 hardware does)
IBM PCjr: Confirm keyboard input triggers INT 02h (NMI)
IBM PCjr: Confirm NMI calls INT 09h (IRQ1)
IBM PCjr: Confirm NMI calls another INT (40h-4Fh? Don't recall right now) to translate PCjr keyboard code to IBM PC compatible.
IBM PCjr: Confirm INT 09h is given the keyboard scan code in AL at entry point (The PCjr ROM cart of Pitfall depends on this)
IBM PC/AT and PS/2: AT type keyboard handler to process input from 8042, verify IRQ1 happens, from hardware.
NEC PC-98: Verify 8251 UART at ports 40h-42h even is attached to keyboard, keyboard input appears on UART, triggers IRQ1. If IRQ1 masked, then no interrupt.
IBM PC/XT/AT: Ask user to hold down keys to verify that keyboard sends DOWN code initially, pauses, repeats DOWN scan code while held, UP when released.
NEC PC-98: Ask user to hold down keys to verify that keyboard sends DOWN code initially, pauses, repeats UP and DOWN scan codes while held, sends UP when released. NOT CERTAIN: Does it send UP again when the last byte was UP?
IBM PC/XT/AT: Modifier keys (CTRL, ALT, SHIFT) generate scan code up/down events like any key would.
IBM PC/AT: Right CTRL, Right ALT generate extended versions of the XT compatible scan codes.
IBM PC/AT: Pause key immediately generates down and up code sequence in one burst, even if user holds the key.
NEC PC-98: Modifier keys CTRL, GRPH, SHIFT generate scan code events like any would, while NUM, CAPS, KANA generate only one scan code byte to reflect the new state. PC-98 keyboards handle the states themselves including LEDs and send a single scan code event to let the host know, rather than make the BIOS or OS implement them as IBM PC/XT/AT does.
IBM PC/AT: Send echo to the keyboard to verify sending data to the keyboard functions.
IBM PC/AT: Send commands to blink and animate the keyboard LEDs to confirm that command works.
IBM PC/AT: Keyboard controller reset, echo, enable/disable keyboard commands
NEC PC-98: Send echo command (what is it?) to the keyboard to confirm the data path to the keyboard through the 8251 UART is working.
NEC PC-98: Send commands (TODO: look them up) to turn on/off keyboard status (and LEDs) of CAPS and KANA.

Not sure:

NEC PC-98: Find Windows 95 compatible laptop, check if Undocumented PC-98 is correct in that the Windows key does nothing unless a command is sent to enable it, then confirm when enabled the key works and what scan code it sends. NOTE: A PC-98 Windows 95 laptop was confirmed to exhibit related behavior where the Windows key did not work if you booted into Windows 95 "safe mode".
IBM PC/XT/AT: Does BIOS INT 16h unmask IRQ1 as part of processing keyboard input? Does it check for pending input and call the interrupt handler to process it?
NEC PC-98: Do BIOS INT 18h keyboard functions unmask IRQ1 as part of processing keyboard input? Does it check for pending input and call the interrupt handler to process it?
Tandy: Does the Tandy also have a full 8255 at 60h-63h or is it something proprietary? Does it act like the IBM PC/XT PPI at least where keyboard input is concerned? Does port 63h work?
Tandy: Do Tandy systems (pre-VGA) alias I/O ports 60-63h anywhere in the 64-7Fh range like the IBM 5150?
IBM PCjr: Confirm whether interrupt controller shows IRQ1 in service at the time it is called. Probably not, since IRQ1 was not triggered by a hardware interrupt from the PIC, but check.
IBM PCjr: Does the NMI interrupt handling do anything to make the IBM PC compatible scan code accessible from port 60h, so that non-PCjr keyboard handlers can work? What lies at port 60h-63h on PCjr?

Real test cases:

Pitfall for IBM PCjr relies on PCjr behavior where INT 09h is given scancode in AL on entry rather than reading the scancode from port 60h.
Quarth for PC-98 during the title screen and demo loop hooks IRQ 1. The interrupt routine (on pressing any key) signals the game to enter the main menu, but does not read the pending keyboard input, though it does acknowledge the interrupt and it does restore the BIOS IRQ1 handler. If the pending data is not read, INT 18h cannot read any additional keyboard input and the menu is unresponsive. Therefore the DOSBox-X implementation that assumes INT 18h keyboard input does some rudimentary keyboard state checking. Does real hardware do that?

Video:

CGA: INT 10h modes 0,1,2,3,4,5,6 are available, 8 and later are not (IBM PC)
CGA: INT 10h mode 7 works, programs CGA output to MDA video timing (IBM PC 1984 BIOS bug noted on test unit)
CGA: BIOS may be too old to store number of text rows in BIOS data area, field is zero (IBM PC BIOS pre-1986, look at BIOS listing of IBM technical reference)
CGA: Vertical and horizontal blanking and vertical retrace can be polled from port 3DAh (IBM PC)
CGA: Polling and timing 3DAh should show 15KHz (NTSC-like) horizontal sync rate, 60Hz (NTSC-like) vertical sync rate (IBM PC)
CGA: Segment B800-BFFF (32KB region) should show video RAM (16KB) repeat twice (B800 and BC00) in any mode (IBM PC)
CGA: CRTC registers officially at 3D4-3D5h, but accessible at any alias from 3D0h-3D7h. (IBM PC)
CGA: Can use 3D8h to set 320x200 or 640x200 graphics without reprogramming the CRTC after setting mode 4, 5, or 6 (IBM PC)
CGA: 80x25 text mode has visible snow at any point in the raster that video memory is written (IBM PC)
CGA: 80x25 text mode snow can be made numerous enough to show that the pattern in the snow is whatever data byte was written by the CPU taking the place of what was supposed to come from video memory (character and attribute) (IBM PC).
CGA: 80x25 text mode snow only happens on all even OR all odd columns. Whether even or odd seems to depend on which character cell the hardware was on when INT 10h was used to set the video mode, after which the even/odd column is consistent until next modeset.
CGA: Can use 3D8h to switch on/off color subcarrier in any mode, visible on composite output (IBM PC)
CGA: Reading 3D8h causes video mode change (IBM PC CGA known bug, 3D8h decode does not distinguish whether I/O is read or write and acts on data lines). Often 3D8h acts as if FFh is written, though it can be any value depending on how data lines float. (IBM PC)
CGA: Port 3D9h can change border color, foreground color, background color, etc. depending on video mode. (IBM PC)
CGA: 6845 cursor position should act as if full 14 bits are matched, expect aliases every 0x4000 words. (IBM PC)
CGA: Start address in text mode behaves as if 13 bits are matched (16KB bytes = 8KB words). This means if you program the 6845 to start video at 0x0000 and the cursor at 0x2000, the cursor won't appear but the text will. (IBM PC)
CGA: Start address in graphics mode behaves as if 12 bits are matched (8KB bytes = 4KB words). bit 13 comes from bit 0 of the character cell scanline counter. (IBM PC)
CGA: Graphics modes do not show a hardware cursor. Never. (IBM PC)
CGA: Graphics modes use only the least significant bit of the row scan line counter to select 8KB bank. The way to make this visible, is to set 40x25 text mode, write a pattern on screen, then write 3D8h to change it suddenly to graphics. The behavior becomes evident by the bytes at (address) and (address+8192) repeating every other scan line within the character cell that would appear as text in text mode. (IBM PC)
CGA: IBM equipment byte (INT 11h) should indicate CGA color (any value other than MDA monochrome). The byte in the BIOS data area that INT 11h should read from should also return the same value.
CGA: 200-line graphics modes should have a row height of 2 scanlines, 200-line text modes should have a row height of 8 scanlines.
CGA: CRTC index register 3D4h (and all aliases of it) are write only.
CGA: Port 3D9h is write only.
CGA: Upper 4 bits of 3DAh are always set. Value is 0xFx.
CGA: I/O port access matches only the low 10 bits i.e. 3DAh can be read from 7DAh, 13DAh, 63DAh etc.
CGA: 6845 registers 0x00 to 0x0D are not readable (returns 0x00). 0x0E-0x0F are readable.
CGA: CRTC index register (3D4h) is only 5 bits wide. Registers will "repeat" every 0x20 indices.
CGA: Max scanline register is only 5 bits wide.
CGA: Only the low 3 bits of the character cell row are used by the character ROM. A row height larger than 8 scanlines will show the character ROM bitmap repeating within the cell.
CGA: Horizontal Displayed controls both the width of the active display area AND number of character cells (WORDs) per row of text. Changing it to 90 changes the memory layout to 90 WORDs per text row.
CGA: Cursor row start/end registers define character row scanlines that cursor is shown on, inclusive, when start <= end. Cursor shown on start <= row <= end.
CGA: Cursor row start/end registers define character row scanlines that cursor is shown on, inclusive, when start > end. Cursor shown on row <= start OR row >= end. start == end + 1 should result in a solid cursor block. start == end + 2 should result in a solid cursor block with one missing scanline at end + 1. This is how you can do solid cursors, or solid cursors with some scanlines missing in the middle.
CGA: Character row counter (text rows) is 7 bits wide. CGA can count up to 128 rows. This is why the graphics modes use a row height of 2 scanlines (128 x 2 = 256) and then the 6845 register for the last character cell height for blanking is used to bring the count to 262 for NTSC-like output.

Test ideas to try:

CGA: Reprogram 80x25 text mode to 80x13 text mode (make row height larger but reduce row count to keep video output same or similar to what the monitor expects). This is to visually show that the CGA only uses the low 3 bits (0-7) of the character cell scanline counter for character ROM.

Hack ideas to try:

CGA: Set 640x200/320x200 graphics, but change row height to 1 (instead of the 2 that makes CGA graphics interleave 2:1) to produce non-interlaced CGA graphics. Increase the blanking border vertically to compensate so the video mode is valid to CGA monitors. The result should be a sort of very "widescreen" non-interlaced graphics area in the center of the display. It should not repeat unless the CGA is asked to show more than an 8KB region. The design of CGA makes it unlikely the second 8KB of ram will ever be visible this way.

Video:

PC-98 INT 18h text layer enable and disable
PC-98 INT 18h graphics layer enable and disable
PC-98 INT 18h AH=42h mode setting, 640x200 upper/lower and 640x400 modes
PC-98 INT 18h AH=42h should reset GDC graphics start address to zero
PC-98 INT 18h AH=42h should reset GDC to 40 display WORDs per text row (80 x 8 bytes)
PC-98 INT 18h AH=42h should update BIOS data area 0:597h, bits 1-0, from bits 7-6 of CH minus 1.
PC-98 INT 18h AH=42h should allow bit 4 to control which display page to show.
PC-98 INT 18h AH=31h should return display status, including mode from AH=42h in bits 1-0.
PC-98 INT 18h AH=11h and AH=12h should show/hide cursor as documented
PC-98 INT 18h AH=0Eh should change display address offset of text layer
PC-98 INT 18h AH=0Ah and AH=0Bh should permit getting/setting CRT mode, including 20/25-line text, 40/80-column text, and vertical lines vs "simple" graphics.
PC-98 INT 18h AH=13h should set cursor position
PC-98 A0000-A1FFF should appear as full read/write 16-bit WORDs. If the value is between 0x0000 and 0x00FF, then it selects one of 256 single-wide ASCII or extended characters. If the value is between 0x0100 and 0xFFFF, then it selects a double-wide character (except, some of the codes represent single-wide still).
PC-98 A0000-A1FFF double-wide characters are stored as if 16-bit but are chosen as if two 7-bit values from the upper/lower bytes of the 16-bit word. This means bits 15 and 7 have no effect on the display of the character. NOTE: Some references for PC-98 explicitly suggest setting bit 7 of the second half of the doublewide character for some reason.
PC-98 A2000-A3FDF should show 16-bit WORDs where only the low 8 bits are read/writeable. This is attribute RAM. 0xE1 should show bright white text on a transparent (usually black background). Second byte on real hardware reads back 0xFF.
PC-98 A3FE0-A3FFF is NOT part of attribute RAM, it is non-volatile memory that by default is read-only unless hardware I/O is carried out to enable writing to it.
PC-98 A4000-A4FFF is a memory region that reads/writes the currently selected character generator bitmap, 16-bit word sized to support double-wide characters. Based on real hardware this region repeats throughout the entire 4KB region.
PC-98 I/O ports A1h, A3h select which character to read/write. A3h is upper, A1h is lower. Character code is the same as what you would write to A0000-A1FFF. Port A5h selects the row, and if reading/writing through port A9h, which 8-bit "half" of the bitmap to read/write. Reads from A9h should match memory region at A4000.
PC-98 character ROM is not writeable except values 0x??56 and 0x??57. ?? can be anything except 00, which would otherwise allow overwriting single-wide ASCII characters. These codes are set aside for custom font bitmaps, which some PC-98 games use heavily in the mid to late 1990s.
Writeable "user defined" range of double-wide characters should appear as written when written to the text layer. Custom character bitmaps should be possible this way.
PC-98 text layer horizontal and vertical lines are rendered over the center of the single wide character cell. Real testing shows it is rendered as if over the left edge of the character cell, then delayed by 4 pixels to center it, therefore a grid of these lines formed from the attributes of a rectangular region of text cells would show that the horizontal lines overlap into the next text cell.
PC-98 blink attribute causes text to blink as if a 2-bit counter, where text is invisible when the counter is zero. It blinks like this: OFF ON ON ON OFF ON ON ON. This counter appears to be the same counter from which the least significant bit is used to blink the hardware cursor (OFF ON OFF ON).
PC-98 text hardware cursor acts as if the "reverse" attribute bit was inverted. If reverse was set, the text cursor is rendered as if reverse was clear, for example.
PC-98 ~"secret" bit blanks the cell as if the font bitmap were blank. It affects no other attribute in the cell.
PC-98 text is rendered per pixel such that it shows either a foreground color or the graphics layer underneath. Note that this includes the ability to specify "black" as a foreground color to mask the graphics layer.
PC-98 cursor covers the width of the character. If the character is single-wide, then it covers the one cell. If the character is double-wide, then it covers both halves and both cells IF the cursor is positioned on the left half (first WORD) of the doublewide character. If the cursor is placed on the right half, then it is only rendered on the right half of the doublewide character.
PC-98 double-wide characters generally start with the left half on the text cell they are written, and the right half is shown on the next cell regardless of the actual contents of the next WORD value in memory. However, there is a range of double-wide characters where this does not happen and correct display requires writing the same 16-bit code to both cells in memory to display. Furthermore there is a range of codes that are 16-bit values that represent single-wide characters (proprietary NEC PC-98 graphics characters it seems) that cover only one text cell.
PC-98 allows the vertical line attribute bit to be re-defined as a flag to enable "simple graphics". In that mode, the vertical line attribute bit means the low 8 bits of the character code are interpreted as a low resolution 2x4 bitmap shown on the text layer.
PC-98 INT 18h AH=0Ah should allow control of "simple graphics" mode.
PC-98 I/O port 68h should also allow control of "simple graphics" mode (values 0x00 and 0x01).
PC-98 640x200 graphics should enable display only every even scanline by default. Writing port 68h (values 0x08 and 0x09 should control this). The every other scanline effect seems to be a way to emulate the 200-line graphics compatible with 15KHz monitors and television displays.
PC-98 graphics should start up in 8-color mode (3 graphics planes, GRB order). The 8-color mode should not permit access to the 4th bitplane at E0000-E7FFF. The color palette registers should only permit remapping the 8 colors to one of other 8 colors (digital RGB output). Writing 0x00 to port 6Ah should switch to this mode and disable the 4th bitplane right away. Real hardware testing shows the hardware acts as if the digital 8-color palette and the analog 16-color palette are stored in separate places, and the palette change to display is instantaneous.
PC-98 writing port 6Ah value 0x01 should enable the "analog" 16-color mode, enable the 4th bitplane at E0000-E7FFF, and cause display output to show the contents of the analog palette right away.
PC-98 I/O ports A8h to AEh even control the color palette. In 8-color mode, these form nibbles the remap the 8-color digital output to other 8-color digital colors. In 16-color mode, A8h is an index into the color palette (only low 4 bits matter) and AA to AEh even are 4-bit wide registers that describe G, R, and B values to send to analog output. Changes are instantaneous (as far as I know)
PC-98 I/O port A6h should control which display "page" CPU writes go to, and A4h should control which display "page" is sent to the display. Changes are instantaneous as far as I know.

Questions:

There is mention in Undocumented PC-98 of an extended text attribute mode that uses the full 16-bit WORD for foreground/background colors. How is that enabled?

Real test cases:

Carat (simple graphics used for score, win/lose messages, high score list atop the graphics of the game)
Touhou Project 2, 4, and 5, uses text layer with solid filled cells to cover up graphics layer except for the top down scrolling game playfield in order to cover up the fact that sprites are not clipped outside the playfield when drawn (probably for performance). Transitions between levels are accomplished by animating all text cells through CG characters appropriate for fade in/out effects. All character cells except score on the right side, game menu selection, and level/music names when displayed, have foreground color set to black.
Eve Burst Error (and any other game by the same company) does not use BIOS or I/O but depends on memory mapped I/O at A4000-A401F to read CG bitmaps. NOTED: On real PC-9821 hardware single stepping into BIOS 18h function to write CG user defined fonts showed that the BIOS will default to memory-mapped I/O as well when carrying out the call.
Touhou Project 2 uses user-defined CG cells for custom font in the menu.
Touhou Project 2, 4, and 5 uses user-defined CG cells for scoreboard on the right.
A bug in Touhou Project 2, 4, and 5 as well as several other games will also try to write a custom CG bitmap over 0x0056 and 0x0057 single-wide ASCII characters, which must be rejected
Rude Breaker uses user-defined CG cells for game score, ship select, menus.
Many games rely on display page flipping, for CPU writes to go to one page while displaying another: Marble Madness, Touhou Project, Rude Breaker, etc. NOTE: The terminology used in PC-98 documentation says display "bank", while I like to use "page".

286+ reset vector tests:

IBM PS/2 and AT: Write CMOS "shutdown byte" values 0x05 or 0x0A, then use keyboard controller, or PS/2 port 92h, or CPU triple fault, or Intel PIIX PCI chipset port CF9h, to reset the CPU. Confirm BIOS reads our intent from CMOS "shutdown byte" and JMPs to 16:16 FAR pointer in BIOS data area (40:67) instead of doing a full system reset. This is how IBM 286-class systems force the CPU back to real mode from protected mode. Confirm as documented, 0x05 does PIC EOI and 0x0A does not do PIC EOI. Confirm that a CMOS "shutdown byte" value of 0x00 causes a normal system reset.
NEC PC-98: Write port 37h to set SHUT0 and SHUT1 to zero, then reset by writing port F0h. Confirm BIOS reads 16:16 FAR stack pointer from BIOS data area 0:404 and RETFs to a 16:16 FAR pointer to resume execution rather than doing a full reset. NOTE: According to documentation, only SHUT0 needs to be zero. Confirm setting SHUT0=1 and SHUT1=1 does a normal system reset, and SHUT0=1 and SHUT1=0 causes BIOS to print "SYSTEM SHUTDOWN" and halt as documented.
IBM PS/2 and AT: Write CMOS "shutdown byte" value 0x09 (undocumented), then reset the CPU. Confirm undocumented but observed behavior that 16:16 FAR pointer in BIOS data area (40:67) is loaded into stack pointer, and then registers are popped off the stack (ES, DS, DI, SI, BP, SP, BX, DX, CX, AX) followed by IRET, to resume execution. Windows 3.1 standard mode (not enhanced mode!) depends on this undocumented behavior if it detects it is running on a 286, it will not use this on a 386 or higher. NOTE: Shutdown mode 0x09 was intended only for the BIOS itself as a way to return from BIOS INT 15h AH=87h function "copy extended memory".

General reset tests:

IBM PC/XT/AT/PCjr/Tandy/etc: JMP F000:FFF0 or JMP FFFF:0000 to re-execute BIOS startup routine. On the original IBM 5150 this works fine. Later BIOSes (386 and up) can differentiate between actual reset and JMP. One Pentium-class BIOS was found to put INT 19h at FFFF:0000, which works because the real entry point on CPU reset is above 1MB i.e. physical address FFFFFFF0 on 486/Pentium systems where BIOSes at that time had begun to store a compressed image in ROM that decompresses itself to RAM and then starts up.
IBM XT? or later: Reset through keyboard controller. Test whether explicitly setting output lines, or the "pulse" commands, or both, have the desired effect.
IBM PS/2 or later: Reset through PS/2 system port 92h. Note that 92h also controls A20 gate.
IBM PC or NEC PC-98 (286 or higher): Switch to protected mode in such a way as to cause a triple fault, which causes the CPU to shut down and reset itself.
IBM PC/AT PCI-based Intel chipsets: Port CF9h has two bits that can be toggled to do a "hard" or "soft" reset. Either one causes a reset of the CPU. I don't remember at this time what the difference between the two is.
NEC PC-98: Writing any value to port F0h should cause a CPU reset.

Real world test cases:

IBM PC/AT: Windows 3.0 and Windows 3.1 real, standard, enhanced mode, cputype=286 and cputype=386. KRNL286.EXE (standard mode kernel) has highest priority.
NEC PC-98: Anything involving VEMM486.EXE (a popular expanded memory manager)
NEC PC-98: "Dragon half", which appears to rely heavily on the reset vector for yet unknown reasons, even though at this time, DOSBox-X does not satisfy the game's requirements to signal disk change.

joncampbell123 / dosbox-x

Test program list/requests (2018 December to 2019 Febrary) #940