Skip to content

Add DOS platform support (DJGPP)#15377

Open
AJenbo wants to merge 41 commits intolibsdl-org:mainfrom
diasurgical:sdl3-dos
Open

Add DOS platform support (DJGPP)#15377
AJenbo wants to merge 41 commits intolibsdl-org:mainfrom
diasurgical:sdl3-dos

Conversation

@AJenbo
Copy link
Copy Markdown
Contributor

@AJenbo AJenbo commented Apr 13, 2026

This is the combined work of @icculus @madebr @glebm @jayschwa @ccawley2011 and me rounding it off with stability fixes and missing features, thanks to everyone for pitching in.

image

This is a fairly complete port to DOS with only minor features like audio recording missing. I have tested it extensively with DevilutionX in DOSBox. But no real hardware testing. The features I didn't add is mostly because I didn't have a good way to test that they worked correctly.

For threading I took some conceptual inspiration from the PS2 port.

What's supported

  • Video: VESA 2.0+ linear framebuffer and VESA 1.2 banked framebuffer, 8-bit indexed color with VGA DAC palette programming, hardware page-flipping with vsync, VBE state save/restore on exit
  • Audio: Sound Blaster 16 (16-bit stereo, up to 44.1 kHz), Sound Blaster Pro (8-bit stereo, up to 22 kHz), Sound Blaster 2.0/1.x (8-bit mono), all via IRQ-driven DMA with double-buffered auto-init
  • Input: PS/2 keyboard with extended scancodes (0xE0 prefix), INT 33h mouse with queried sensitivity, gameport joystick via BIOS INT 15h with auto-calibration
  • Threading: Cooperative scheduler using setjmp/longjmp with stack patching. Real mutexes, semaphores, TLS, and condition variables (generic fallback). Yield points in the event pump and delay functions keep audio and other threads responsive.
  • Timer: Native PIT-based timer using DJGPP's uclock() at ~1.19 MHz resolution
  • Filesystem: GetBasePath / GetPrefPath via DJGPP's searchpath(), POSIX filesystem ops fallback
  • Build: CMake cross-compilation toolchain file, DJGPP CI job, preseed cache for faster configure

What's NOT included

  • Audio recording playback only
  • VGA Mode 13h no fallback for systems without VESA
  • SDL_TIME native implementation reuses Unix gettimeofday via DJGPP's POSIX layer (works fine)

How to build

cmake -S. -Bbuild-dos \
  -DCMAKE_TOOLCHAIN_FILE=build-scripts/i586-pc-msdosdjgpp.cmake \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build-dos -j$(nproc)

icculus and others added 30 commits April 13, 2026 08:50
Seeking breaks otherwise. We might be able to just fflush() before or seeking
instead?
Turns out DosBox-X was having trouble with the Sound Blaster or something;
standard DosBox works correctly directly from the interrupt handler, and
without doubling the buffer size.
This is MUCH faster than just leaving buffering disabled, and also works
around getting bogus reads after an fseek. SDL_LoadWAV on test/sample.wav
no longer takes several seconds to finish, and comes up with the correct
data.

I wonder if we're triggering this in LoadWAV because we're malloc'ing data
between seeks/reads, and it's causing the djgpp transfer buffer to change. Or
maybe the Fat DS trick is confusing it? I don't know, I haven't had time to
debug it, it might just be a legit libc bug in djgpp too, for all I know.
This uses an old trick we used in SDL 1.2 for MacOS Classic, which did its
audio callback in a hardware interrupt. If the audio is locked when the
interrupt fires, make a note of it and return immediately. When the lock is
released, if the interrupt has been fired, run the audio device iteration
right then.

Since there isn't a big device lock in SDL3 (available to the app, at least),
this keeps a counter of when any SDL_AudioStream is locked, which is probably
good enough.
This uses VESA interfaces to manage the display and works with the software
renderer.

Events aren't hooked up yet, so prepare to close DosBox on each run.  :)
This gets most of the rendering examples, which use SDL_GetBasePath() to
find textures to load, working.
Of course Quake 1 solved this better, haha. It's smart: less memory, dirt
simple, and you don't even have to worry about synchronizing with the
interrupt handler, because it's safe for both sides no matter when an
interrupt fires.
[sdl-ci-filter djgpp]
[sdl-ci-artifacts]
- SDL_runapp.c: Add SDL_PLATFORM_DOS to the exclusion list so the
  generic
  SDL_RunApp() is disabled when the DOS-specific one is compiled.
- SDL.c: Exclude SDL_Gtk_Quit() on DOS. DJGPP defines __unix__ which
  sets
  SDL_PLATFORM_UNIX, but DOS has no GTK/display server. The GTK source
  is not compiled (CMake UNIX is false for DOS) so this was a link
  error.
- sdlplatform.cmake: Add DOS case to SDL_DetectCMakePlatform so the
  platform is properly detected from CMAKE_SYSTEM_NAME=DOS.
- i586-pc-msdosdjgpp.cmake: Add i386-pc-msdosdjgpp-gcc as a fallback
  compiler name, since some DJGPP toolchain builds use the i386 prefix.
- Implement double-buffered page-flipping for VBE modes with >1 image
  page
- Save and restore full VBE state on video init/quit for clean mode
  switching
- Improve DOS keyboard handling: support extended scancodes and Pause
  key
- Lock ISR code/data to prevent page faults during interrupts
- Always vsync when blitting in single-buffered modes to reduce tearing
Move audio mixing out of IRQ handler to main loop for improved
stability and to avoid reentrancy issues. Add SDL_DOS_PumpAudio
function, update DMA buffer handling, and adjust sample rate to 22050
Hz.
Silence stale DMA buffer halves to prevent stutter during load.
Detect SB version and select 8-bit mono or 16-bit stereo mode.
Handle DMA and DSP setup for both SB16 and pre-SB16 hardware.
Add FORCE_SB_8BIT option for testing in DOSBox.
- Poll Sound Blaster DSP status instead of fixed delay after speaker-on
- Clarify DPMI conventional memory is always locked; update comments
- Document and justify DMA memory allocation strategy
- Free IRET wrapper after restoring interrupt vector to avoid leaks
- Throttle joystick axis polling to ~60 Hz to reduce BIOS timing loop
  cost
- Always poll joystick buttons directly for responsiveness
Implement banked framebuffer access for VBE 1.2+ modes without LFB.
Detect and initialize banked modes, copy framebuffer data using bank
switching, and blank the framebuffer on mode set. Page-flipping is
disabled in banked mode.
@icculus
Copy link
Copy Markdown
Collaborator

icculus commented Apr 15, 2026

Have you considered supporting dlopen() for LOADSO, and also DXE shared libs?

I hadn't gotten around to it, but when I researched this, your work on porting Quake 2 to DOS came up. :)

I don't think there was a good reason not to support it, I think I just hadn't filled in the code yet.

@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 15, 2026

... how about that become a follow up to this PR instead of part of it?

@icculus
Copy link
Copy Markdown
Collaborator

icculus commented Apr 15, 2026

Also, the fat DS pointer doesn't disable all crash protection. The CPU can no longer notice that you're dereferencing memory past end of your data segment and raise an exception, since the data segment now starts at zero and goes for 0xFFFFFFFF bytes, but you still will get exceptions if you overrun a memory page into one that isn't mapped. In that sense, it isn't much different than how Linux works.

But the base 640k area, where all sorts of important stuff lives, will be mapped in, and you can absolutely wreak havoc with a NULL pointer in this regard, I imagine.

Also, the djgpp docs/faqs on fatDS are basically like "NEVER DO THIS," but I do tend to believe them to be overblown. Quake 1 did it and no one cared and/or DPMI hosts might have quietly been upgraded to handle it.

Removing the fat DS trick means we'll need to have a shadow surface for the video output, which would affect SDL_GetWindowSurface() (and the software renderer), and maybe be a performance hit, but maybe that's not a big deal in practice...? It might mean we never get tearing either, since we can guarantee VRAM is updated in one block under SDL's control, too.

I think the SoundBlaster DMA code would be affected, too, but that feels like a lot less data to move around at once.

@icculus
Copy link
Copy Markdown
Collaborator

icculus commented Apr 15, 2026

... how about that become a follow up to this PR instead of part of it?

For shared object loading? That's 100% fine with me.

@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 15, 2026

I think the SoundBlaster DMA code would be affected, too, but that feels like a lot less data to move around at once.

Getting sound to not constantly stutter was fairly painful already. I can try and hack some thing together to test it out, if I do I'm going to compare it on either PCem or real hardware (though I don't have anything below PII class lying around.

On an almost unrelated note I got multiplayer working between the DOS and Linux port of DevilutionX:
image

@sezero
Copy link
Copy Markdown
Contributor

sezero commented Apr 15, 2026

Have you considered supporting dlopen() for LOADSO, and also DXE shared libs?

I hadn't gotten around to it, but when I researched this, your work on porting Quake 2 to DOS came up. :)

I don't think there was a good reason not to support it, I think I just hadn't filled in the code yet.

Yes, both q2dos and uhexen2 are good examples.

Major problem is, unlike unices or windows, libc is a
static library, therefore, libc calls need exporting
from the exe in order to satisfy the missing symbols
in SDL3.dxe, which might probably be solvable in the
SDL_main headers.

As for loadso support, existing dlfcn code may probably
enough.

I'm perfectly OK with re-licensing any dxe code in q2dos/uhexen2
as zlib for SDL:
https://github.com/sezero/uhexen2/blob/master/engine/h2shared/dxe.c
https://github.com/maraakate/q2dos/blob/master/dos/dxe.c

... how about that become a follow up to this PR instead of part of it?

That's fine by me.

@ccawley2011
Copy link
Copy Markdown
Contributor

A few more points I spotted while working on ArcEm:

  • The SDL cursor seems to have rendering issues in certain RISC OS modes - typically it ends up as a white rectangle, with occasional inverted colours underneath what should be the transparent part of the image. I'm guessing it's not handling palette changes correctly?
  • For some reason when using SDL_GetClosestFullscreenDisplayMode for 640x480, it's able to get an exact matching mode, but when using 320x256 it gets centred within 1280x1024 despite 640x480 being a closer match.
  • Should anything special be done for log messages/asserts/message boxes while a graphics mode is set?

@LekKit
Copy link
Copy Markdown

LekKit commented Apr 15, 2026

My two cents: It would be nice to have preemptively scheduled threading via PIT interrupt. This is for example done in HX DOS Extender (Win32 implementation over DOS, similar to Wine).
This will likely fix sound jitter as well as help software which actually performs blocking computations in other threads. One example that comes to mind is emulators, which commonly run a CPU execution loop in separate thread which requires preemption for other threads to run.

@jpernst
Copy link
Copy Markdown

jpernst commented Apr 15, 2026

My two cents: It would be nice to have preemptively scheduled threading via PIT interrupt.

The main problem with this is that most DOS functions are non-reentrant, so you can only perform IO from one thread at at time. This would require a file IO abstraction to prevent multiple threads from attempting to read/write a file at the same time. Certainly doable, but normal C code that happens to use fread/fwrite from different threads will certainly break badly.

@icculus
Copy link
Copy Markdown
Collaborator

icculus commented Apr 15, 2026

Getting sound to not constantly stutter was fairly painful already.

Removing fat DS is also not a requirement for this PR, to be clear. If someone wants to take a run at it, having the discussion here is totally appropriate, but it's not a hoop I expect you to jump through.

@icculus
Copy link
Copy Markdown
Collaborator

icculus commented Apr 15, 2026

I got multiplayer working

Also: holy moly!

@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 15, 2026

Alright, I'm going over the rest of the feedback atm to polish things up. Thanks for setting the scope.

- Fix fullscreen default resolution
- Improve best mode matching
- Fix builds on GCC older than 7.0
- Fix text input events
@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 15, 2026

Gave this a very quick build test using a gcc-3.4.6 toolchain (yes,

@sezero thanks, I put a guard in the CMake pressed and applied your patch so that it should now build on your ancient tool chain.

@ccawley2011:
* The SDL cursor seems to have rendering issues in certain RISC OS modes - typically it ends up as a white rectangle, with occasional inverted colours underneath what should be the transparent part of the image. I'm guessing it's not handling palette changes correctly?

I'm not sure how to address this without an easier way to reproduce this :)

* For some reason when using `SDL_GetClosestFullscreenDisplayMode` for 640x480, it's able to get an exact matching mode, but when using 320x256 it gets centred within 1280x1024 despite 640x480 being a closer match.

This should work now. ... but please give it a try.

* Should anything special be done for log messages/asserts/message boxes while a graphics mode is set?

I could have it drop to CLI and render a TUI dialog, we already track the resolution so it should be less scary then it sounds. That said this would not be the first platform not to have a messaging system.

@icculus
Copy link
Copy Markdown
Collaborator

icculus commented Apr 16, 2026

I could have it drop to CLI and render a TUI dialog, we already track the resolution so it should be less scary then it sounds.

(Also not for this PR. Expect me to say this in reply to any other feature requests.)

@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 16, 2026

I have now tested on PCem, it took a couple of additional tweak to the fat DS mode to get it to both boot and exit cleanly.

Update, I tested and confirmed it working with:

Sound Blaster 1.5
Sound Blaster 2.0
Sound Blaster Pro v1
Sound Blaster Pro v2
Sound Blaster 16
Sound Blaster AWE32

S3 Trio64 (VBE 1.2)
S3 ViRGE (VBE 2.0)
Voodoo 3 (VBE 3.0)

I also confirmed that it works on Pentium, which is a step below what we can do easily for Win 9x as GCC uses a Pentium Pro instruction in the crt0 blob by default.

DevilutionX require a 200Mhz CPU before things start running smoothly, but that's also what we experienced under Win9x with SDL1.2.

Update update: With a bit of sprinkeling of SDL_Delay(0) I now have smooth audio working in sub 20fps which is below the original Diablo's frame lock.

If anyone want's to test they can grab a build here: dosablo.zip
(place it next to spawn.mpq or diabdat.mpq)

@madebr
Copy link
Copy Markdown
Contributor

madebr commented Apr 16, 2026

How does a thread yield? SDL_Delay(0)?

It actually only triggered if given a positive value, but yielding on 0 makes sens since that allows applications to provide time for potential other threads without adding any unnecessary sleep.

Perhaps DOS should define the SDL_CPUPauseInstruction macro as SDL_Delay(0)?

@ccawley2011
Copy link
Copy Markdown
Contributor

ccawley2011 commented Apr 16, 2026

  • The SDL cursor seems to have rendering issues in certain RISC OS modes - typically it ends up as a white rectangle, with occasional inverted colours underneath what should be the transparent part of the image. I'm guessing it's not handling palette changes correctly?

I'm not sure how to address this without an easier way to reproduce this :)

I've provided a standalone test case: ccawley2011@2c12cfc

It's not perfect since the palette doesn't include black or white, but it does demonstrate the issue with transparency.

* Should anything special be done for log messages/asserts/message boxes while a graphics mode is set?

I could have it drop to CLI and render a TUI dialog, we already track the resolution so it should be less scary then it sounds. That said this would not be the first platform not to have a messaging system.

I wouldn't worry about anything too complicated - since SDL_ShowSimpleMessageBox returns a failure code if an error can't be displayed, individual applications can still provide fallbacks using other toolkits (e.g. ImGui). The one thing that might be a good idea to address now though is to ensure that SDL_Log() doesn't write to the screen while in a graphics mode to avoid rendering issues.

@ccawley2011
Copy link
Copy Markdown
Contributor

It looks like the DOS port is affected by issue #9343 - SDL_SetDisplayModeForDisplay assumes that because it's switching into a mode with the same parameters as the "desktop" mode it can return without calling the driver SetDisplayMode, but that results in it not being switched from text mode to graphics mode unless SDL_SetWindowFullscreenMode is manually called by the user with a different mode.

Comment thread test/testsem.c Outdated
Comment thread test/torturethread.c Outdated
Comment thread test/torturethread.c Outdated
SDL_zero(data->mapping);
}

// Restore saved VBE state if available.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it be possible to only do this if a previous mode change succeeded?

Co-authored-by: Cameron Cawley <ccawley2011@gmail.com>
@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 16, 2026

I wouldn't worry about anything too complicated - since SDL_ShowSimpleMessageBox returns a failure code if an error can't be displayed, individual applications can still provide fallbacks using other toolkits (e.g. ImGui).

Yeah DevilutionX does something to this effect, once the graphics system is booted it will render it's own error dialogs. That's pretty common for most games afaik. We also fall though to stderr if none of the other systems are available.

@ccawley2011
Copy link
Copy Markdown
Contributor

I've also opened issues #15395 and #15396, which are related to the DOS port but not specific to it.

Comment on lines +357 to +358
keyevents_ringbuffer[keyevents_head] = inportb(KBD_DATA_PORT);
keyevents_head = (keyevents_head + 1) & (SDL_arraysize(keyevents_ringbuffer) - 1);
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What would happen here if the ring buffer gets full while the main thread is busy?

@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 16, 2026

Lets go the extra mile:

image

@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 17, 2026

output.mp4

No audio but I think that's because I don't have the right configuration, but it's to late to mess any more with this for today.

@AJenbo
Copy link
Copy Markdown
Contributor Author

AJenbo commented Apr 17, 2026

Alright I got audio working today (system configuration), doing so also fixed quitting so maybe there is something to be debugged there.

Performance on real hardware isn't fantastic, I build a small test game (320x200) and just rendering it's primitive UI caps out at 24fps on real hardware, with audio i drop to 19fps and with graphics it's at 9fps

This is a 300mhz machine (all parts are from 1998 or older) scoring 30.7fps on PcPlayer Benchmark (640x400) so not being able to do so on a mostly blank screen is not good.

UPDATE: Found some issues in the mode detection code, we are now at 205fps for a simple UI, 185fps with audio on top of that and ~20fps for this thing:

output.mp4

(game volume is extremely low, but there is 11khz real time music mixed with 22khz sfx)

This actually scales pretty well with my modern Linux system where it's roughly 1fps per Mhz for empty frames (not just in this game) so I think performance is roughly where we would want it to be on real hardware.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants