flat assembler
Message board for the users of flat assembler.

Index > DOS > [Beginner’s Guide] Set up Dosbox for Programming with FASM

Author
Thread Post new topic Reply to topic
Hans-Joachim Rudolph



Joined: 29 Jan 2023
Posts: 3
Hans-Joachim Rudolph 01 Aug 2023, 22:04
Many things in this guide are covered elsewhere. Namely
there is Privalov’s video, there is an elaborate guide from
Vladimir Igonin (in Russian) and, of course, the wealth of
information here in the DOS section. So I hope this guide
still finds it’s niche! In the end you should have a develop-
ment environment with many kinks already ironed out, so
you may have a maximally pleasurable programming
experience.
Code:
Let me assume, you are a beginner in both assembler and DOS,
BUT you have installed things before and you basically  know
what a command line does and is used for.

Part 1: Set up a basic DOS system with FASM

(1)    Download  Dosbox  for  your platform from dosbox.com,
       install it and run it.  You should  see  the  command
       prompt coming up showing ’Z:\>’.  Hit Ctrl+F1 to open
       the Keymapper and hit ’Save’.  Close the mapper  with
       ESC, then close Dosbox with the command ’exit’.

(2)    You  will  need  to  find the configuration files for
       dosbox on your system.  It is in ~/.dosbox for  Linux
       and %LOCALAPPDATA%\DOSBox for Windows.

(2.1)    Create a directory where your DOS files will reside
         (e.g. ~/.dosbox/drive_c).

(2.2)    In ~/.dosbox replace the dosbox*.conf (current ver‐
         sion 0.74‐3) with this:

         [cpu]
         cycles=4000 # alleviate impact of busy waiting
         [sdl]
         mapperfile=mapper.map # see next sub step
         [autoexec]
         mount c ~/.dosbox/drive_c
         c: # change right away to our mounted drive folder

         Maybe  do a backup of the original, but you can al‐
         ways start over by just deleting the  configuration
         files and restarting Dosbox. ’Busy waiting’ may un‐
         necessarily heat up your  processor  and  eat  away
         your  laptop’s  battery, but it is normal with many
         DOS programs.  Look it up, if you have not heard of
         it before!

(2.3)    In  the same folder, rename the *.map file and call
         it mapper.map.  Then edit it: You will want to  re‐
         move most of the lines that start with ’hand_’.

         Dosbox  uses  most  function keys for itself.  This
         may have  surprising  effects,  e.g.  you  want  to
         compile  (only)  in fasmd (Ctrl+F9), but this combo
         is pre‐set to  kill  Dosbox!   Thus  it’s  wise  to
         delete these lines in mapper.map.

         Do NOT remove the line with ’hand_capmouse’ though!
         This will keep you from getting  your  cursor  back
         with  Ctrl+F10,  should Dosbox have captured it.  I
         actually rebound it to Ctrl+Esc with "key 27  mod1"
         to have the function keys clear.

(3)  Install  fasm for DOS from flatassembler.net.  Just un‐
     pack everything to ~/.dosbox/drive_c/fasm.

(4)  Start Dosbox. Your first FASM  session  may  look  like
     this:

     C:\>cd FASM
     C:\FASM>fasm
     flat assembler  version 1.73.31
     error: no 32‐bit DPMI services available.

     One  solution  is  to  get  the  HX  DOS‐Extender  from
     Japheth.  From the runtime you  only  need  to  extract
     said  DPMI  server  (hdpmi32.exe)  and place it in your
     drive_c folder. Execute this file before starting  fasm
     and you should see the program telling you it’s command
     line options, which means it works.

     Should you notice, that this magic only works once  and
     you  need  to execute hdpmi32.exe again after each fasm
     run, try running ’hdpmi32 /r’ :) As a  bonus,  you  can
     add  this  line  to your dosbox*.conf in the [autoexec]
     paragraph.

(5)  Start the FASM DOS IDE (fasmd.exe). Hit F4 and navigate
     to  EXAMPLES\COMDEMO and open comdemo.asm. You will see
     a simple ’Hello world!’ example.  Hit F9 to compile and
     run  it.  You  may  just see a short flicker, since the
     program terminates instantly.

     You can hit Alt+F5 to see the user  screen  (it  should
     show  the ’Hello world!’  message). You can, of course,
     also alter the code to your liking.  Without going into
     detail, insert the following just above ’int 20h’:

     mov  ah,7
     int  21h

     Hit  F9!  Now you should have plenty of time to look at
     your program’s output.
    

That's it for the first part. Please send me your feedback.
Is there somewhere I should elaborate more or be more terse?
This is just a write-up of the notes that I make as I go.
There is plenty of room for mistakes.
If you note any, please let me know.

Is there anything that should be part of future guide parts?
So far I have noted:

  • creating symbols, compiling listings.asm and creating a listing of comdemo.asm
  • debugger (so far without symbols, or maybe pecvt is somehow compilable under dos?)
  • HelpPC as TSR, RBIL
  • configure an OFM (my fav: VC) for work with FASM
Post 01 Aug 2023, 22:04
View user's profile Send private message Reply with quote
xoxo



Joined: 20 May 2025
Posts: 1
xoxo 20 May 2025, 12:14
EDIT: phrasing, added PS;

Thanks a bunch for writing this! Found all info useful, including the keyboard shortcuts You mentioned at the end. Eager to learn more about your workflow with helpPC and volkov!

xoxo

PS. Keys for starting the mapper on my system were a little different in a default installation: [F11/F12]+M. As per official docs: https://dosbox-x.com/wiki/Home
Post 20 May 2025, 12:14
View user's profile Send private message Reply with quote
Hans-Joachim Rudolph



Joined: 29 Jan 2023
Posts: 3
Hans-Joachim Rudolph 04 Oct 2025, 23:43
Here is some more for beginners. This is just preliminary for the next part where we'll write a graphical animation that replicates an effect seen in a well-known DOS era game.

Code:
Part 2: Graphical template

Playing  with  graphics  (VGA  in this case) is a nice way to get
started.  On the one hand it’s quite nice  to  look  at,  on  the
other hand it’s rather easy.  You just write into some memory lo‐
cation  and  pixels start to appear on your screen.  But you need
to switch DOS into a graphical mode first.  The most  popular  by
far is typically referred to as mode 13 (13h, $13 or 0x13 depend‐
ing on your preference).

Here  is  an example how you can draw a single pixel.  Save it in
Dosbox, open it with fasmd and run it straight away with F9  like
you  saw  in  the last part.  You should see a black screen and a
tiny white dot in the upper left.

        org     $100

        mov     ax,$13
        int     $10             ; set up video mode

        push    $A000
        pop     fs              ; set up video segment address
        mov     byte[fs:0],$F   ; paint a single white pixel

        mov     ah,7
        int     $21             ; wait for keypress

        mov     ax,3
        int     $10             ; return to 80x25 chars text mode

        int     $20             ; exit program

The first line is practically all the boilerplate  that’s  needed
to  write  a  COM file.  COM files are way easier than EXE files.
They are loaded into memory and then  code  starts  executing  at
$100.   That’s  what  this  first  line is for.  It tells FASM to
start generating addresses at this origin.

The next two lines you’ll see an interrupt request, which is  the
common  way  to  talk  to the OS, BIOS, CPU and so on.  In higher
languages you use API functions calls that would  look  something
like  VideoBios(0, 0x13).  In assembly the MOV instruction can be
thought of as setting the arguments to the call.  There  are  two
arguments because AX is a 16‐bit register which consists of 8‐bit
AH  (high) and AL (low).  So this one line sets AH to 0 and AL to
$13.  The next line actually hands other the  control.   You  can
consult  HelpPC  for this particular one by looking for INT 10,0.
There you’ll see that INT 10 handles video requests,  AH  (0)  is
for the function that you request (set video mode) and finally AL
($13)  is the actual first "argument".  The mode is then switched
to $13.  This is a multi‐color video  mode  with  320x200  pixel.
Now we can simply write into video memory, but there is one prob‐
lem.

In DOS we typically have 16 bit wide registers.  The highest num‐
ber  they can handle is $FFFF = 65535.  The video that we want to
address, however, is at $A’0000.  See how this is one hexadecimal
digit (four bit) more?  We need a second register  to  keep  this
information.   This  is  where  the  segment register (fs in this
case) comes in.  We set this up with $A000 (three zeroes).   When
we use it in [fs:0] a line later the CPU interprets it: It shifts
$A000  left  which makes it $A’0000 and adds the value behind the
colon (which is 0 in this case).  That’s roughly how you  address
20‐bit  addresses  on 16‐bit DOS and a very basic introduction to
Memory Segmentation on x86.

The next line  actually  draws  the  pixel.   MOV  moves  (rather
copies)  data.   In this case it moves a color value ($0F) to the
first address of the video RAM.  The very first  address  of  the
video  RAM  is shown in the upper left corner of the screen.  You
could replace the zero in [fs:0] with another number and  hit  F9
again  to  run the code.  Start small value and make your way up.
You should notice the white dot starts moving right.   Eventually
you’d  hit the right end of the screen and the dot just skips the
beginning of the next line.  It’s the same way we read text.

With HelpPC or searching the internet you’ll likely decipher  the
next  interrupt  requests easily.  The first is meant as a conve‐
nience.  It just keeps your program running until you have  found
your  pixel  on  screen.   The next switches back to the original
text mode.  The last int exits the program.  You need  to  return
control  to  the  DOS  command interpreter otherwise your program
will just hang in the end and you need to restart the computer or
Dosbox.
    


xoxo, thanks for your feedback. :) Is there something you'd like to see in a future part?
Post 04 Oct 2025, 23:43
View user's profile Send private message Reply with quote
Display posts from previous:
Post new topic Reply to topic

Jump to:  


< Last Thread | Next Thread >
Forum Rules:
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum
You cannot attach files in this forum
You can download files in this forum


Copyright © 1999-2025, Tomasz Grysztar. Also on GitHub, YouTube.

Website powered by rwasa.