Susam's DOS Pages

Good Quality DOSBox Video Capture

2020-09-01T00:00:00Z

Vintage DOS Programs

Once in a while, I fire up one of the vintage DOS games or language interpreters in DOSBox for nostalgia's sake. DOSBox is an emulator program that emulates IBM PC compatible computers running DOS. Trying my hands on these antiquated DOS programs now evokes old memories from my childhood days days when I first came across computers as part of our primary school curriculum.

Computers were much simpler in those days. The ones in our school were IBM PC compatible computers with mostly monochrome displays. A couple of them had support for a very limited number of colours provided by CGA or EGA graphics cards. The ability to boot a computer using a 5¼-inch floppy disk containing MS-DOS, load a Logo or BASIC interpreter or a computer game from another floppy disk and then write some programs or play a few games without any distraction had its own charm that I find missing from modern day computing.

Often while using old DOS programs with DOSBox in this day and age, I want to take screenshot captures or video captures of the DOSBox sessions and share them with my friends. In this article, I will explain how I create good quality screenshot captures and video captures of DOSBox sessions in formats that I can share with others.

Vintage DOS Programs
Software Versions
IBM PC Logo in DOSBox
Digger in DOSBox
DOSBox Screenshot Capture
DOSBox Video Capture
DOSBox Audio/Video Capture
DOSBox GIF Animation
References

Software Versions

Since this article involves several pieces of software, some of what is written here may not hold good in future if the behaviour of any of these software tools change in future. The list below contains the versions of all software tools that were used to test the commands provided in this article:

macOS High Sierra 10.13.6
DOSBox 0.74-3
FFmpeg 4.3.1
ImageMagick 7.0.10-28
IBM Personal Computer Logo Version 1.00
Digger (Original PC booter version by Windmill Software)

Note that both Logo and Digger programs in the list above are DOS programs that were released in 1983. They cannot be run directly on modern computers but they can be run with DOSBox since it emulates old IBM PC compatible computers.

IBM PC Logo in DOSBox

IBM Personal Computer Logo developed by Logo Computer Systems Inc. (LCSI) in 1983 was the first piece of software I got introduced to while learning computers as a kid. I came across it at the age of 8 when I was in Class 4 and our school had a 5¼-inch floppy disk with IBM PC Logo on it. As a result, Logo was the first programming language I learnt in my life. About 20 years later, I would realise that the first programming language I learnt is a dialect of Lisp. How wonderful!

Welcome screen of IBM Personal Computer Logo

If the Logo interpreter program LOGO.COM exists in the current directory, it can be run with DOSBox using the following command:

dosbox LOGO.COM

One of the things I enjoyed drawing with Logo was a grid of overlapping circles like this:

Grid of circles drawn with IBM Personal Computer Logo

Here is the Logo source code for the above output:

REPEAT 20 [REPEAT 180 [FD 1 RT 2] RT 18]

Digger in DOSBox

At around the same time I learnt Logo, I also came across Digger, a computer game for IBM PC developed by Windmill Software in 1983.

Welcome screen of Digger

If the Digger program DIGGER.COM exists in the directory, it can be run using DOSBox with the following command:

dosbox DIGGER.COM -c "config -set cpu cycles=500" -machine cga

The -machine cga option emulates a machine with Colour Graphics Adapter (CGA) because Digger requires a machine of this type to run correctly. The cycles=500 configuration option slows down the speed at which DOSBox emulates instructions in order to emulate the slow machines of olden days. Without this option, Digger runs too fast to be able to be conveniently playable.

A game of Digger that has just begun

Digger has an excellent gameplay where the player digs through underground tunnels to pick up emeralds, drop gold bags to release the gold or squash nobbins and hobbins, collect the released gold to earn more points and so on. It uses bright and attractive colours. The music is great. When Digger was released in 1983, it was quite advanced for its time.

DOSBox Screenshot Capture

The screenshots above were obtained by running IBM PC Logo and the original 1983 PC booter version of Digger on DOSBox and then resizing the screenshots such that their aspect ratio matches the aspect ratio of old CRT computer monitors.

To obtain the screenshots, we first press ctrl+f5 while DOSBox is running. The paths of the screenshots appear in the console output at the terminal where DOSBox was launched. For example:

Capturing Screenshot to /Users/susam/Library/Preferences/capture/logo_000.png
Capturing Screenshot to /Users/susam/Library/Preferences/capture/logo_001.png

Capturing Screenshot to /Users/susam/Library/Preferences/capture/digger_000.png
Capturing Screenshot to /Users/susam/Library/Preferences/capture/digger_001.png

The screenshots obtained in this manner have an aspect ratio of 8:5 which makes the output look stretched horizontally. The old CRT computer monitors for which these old DOS programs were written had an aspect ratio of 4:3 instead. This stretched look can be fixed by resizing the images to an aspect ratio of 4:3. Here are the commands used to fix the aspect ratio and produce the images:

convert logo_000.png -sample '1920x1440!' dosbox-logo-0.png
convert logo_001.png -sample '1920x1440!' dosbox-logo-1.png

convert digger_000.png -sample '1920x1440!' dosbox-digger-0.png
convert digger_001.png -sample '1920x1440!' dosbox-digger-1.png

The convert program comes with ImageMagick. There are a few things worth noting here:

We use the -sample option here to resize the image as opposed to using -resize or -scale. The -resize or -scale option would smooth the jagged edges in the text and graphics by introducing additional colours. The -resize option is great for real world images where we do want the edges to be smooth while scaling up or down but in these screenshots we want to retain the crisp and jagged edges that is typical of DOSBox and the old CRT monitors. Therefore we use the -sample option that does not introduce any new colours. Instead it uses nearest-neighbour interpolation (point sampling) to decide the colours of the scaled image.
The ! flag is used to ignore the aspect ratio of the original image. Without this flag, the output files would be 1920x1200 in size, that is, the largest size with an aspect ratio of 8:5 that fits in a 1920x1440 box. With this flag, the original aspect ratio of 8:5 is ignored and the output is exactly 1920x1440 in size.

DOSBox Video Capture

To start capturing video of DOSBox, we press ctrl+alt+f5. The same key combination stops capturing video. The following output appears in the console output to show where the video file is saved:

Capturing Video to /Users/susam/Library/Preferences/capture/logo_000.avi
Stopped capturing video.

Say, I want to share a video capture of DOSBox with Logo running on it with my friends who might be on devices that do not support playing AVI files. The following FFmpeg command converts the video to a format that can be distributed widely and played on a wide range of devices and players:

ffmpeg -i logo_000.avi -an -c:v libx264 -preset veryslow \
       -crf 17 -vf format=yuv420p,scale=1920:1440:flags=neighbor,fps=30 \
       dosbox-logo.mp4

Here is what the output looks like:

Video capture of IBM Personal Computer Logo [MP4]

Let us briefly discuss the various FFmpeg options used here:

-i logo_000.avi

This, of course, specifies the input file.
-an

The audio is silent in this video, so we reduce the file size a little by disabling the audio stream with this option. For example, without this option the output file size was 317 KB but with this option it turned out to be 282 KB.

This option should not be specified if the audio stream needs to preserved, for example, with DOS games that have audio. We will see an example of this in the next section.
-c:v libx264

This option selects the x264 encoder to encode the video stream into H.264 format. H.264 is also known as MPEG-4 Part 10, Advanced Video Coding (MPEG-4 AVC). Currently, it is the most popular format for recording, compression and distribution of video content.
-crf 17

This option provides visually lossless output, that is, high quality output without any loss in quality that can be perceived by human eyes. For completely lossless output, we need to use the -crf 0 option. However, this option sets the video profile to High 4:4:4 Predictive which prevents the video from playing in some video players. This issue is discussed in more detail in the point about yuv420p pixel format that comes later in this list. Since -crf 0 cannot be used due to this issue, the next best option is -crf 1 which while not completely lossless is much better than visually lossless. Since it trades quality for output size, the output file turns out to be 319 KB in size. The -crf 51 option produces the most lossy output, that is, the worst quality output with a file size of 159 KB.
-preset veryslow

This option provides better compression at the cost of encoding speed. For example, without this option it produces an output of size 355 KB in about 16 seconds on my system but with this option it produces an output of size 282 KB in about 31 seconds on the same system.
-vf format=yuv420p

This video filter option ensures that the output video file can be run in a wide range of devices and players.

For example, without this video filter option, we get the output in the YUV 4:4:4 planar format. I found that QuickTime Player version 10.4 on macOS High Sierra as well as Android 9.0.0 was unable to play this format.
```
$ ffmpeg -v quiet -i logo_000.avi -an -c:v libx264 dosbox-logo.mp4
$ ffprobe -v error -show_entries stream=codec_name,profile,pix_fmt dosbox-logo.mp4
[STREAM]
codec_name=h264
profile=High 4:4:4 Predictive
pix_fmt=yuv444p
[/STREAM]
```
With this video filter option, we get the output in the YUV 4:2:0 planar format. Now both QuickTime Player version 10.4 as well as Android 9.0.0 could play this format.
```
$ ffmpeg -v quiet -i logo_000.avi -an -c:v libx264 -vf format=yuv420p dosbox-logo.mp4
$ ffprobe -v error -show_entries stream=codec_name,profile,pix_fmt dosbox-logo.mp4
[STREAM]
codec_name=h264
profile=High
pix_fmt=yuv420p
[/STREAM]
```
For maximum compatibility with very old or obsolete devices, we could add the -profile:v baseline option that setst the video profile to Constrained Baseline. This option is not recommended unless we really need to support old or obsolete devices. We also need to keep in mind that the baseline profile does not support lossless encoding with the -crf 0 option. The least lossy encoding option we can specify with this profile is -crf 1 which while not technically lossless is much better than visually lossless.
```
$ ffmpeg -v quiet -i logo_000.avi -an -c:v libx264 -vf format=yuv420p -profile:v baseline dosbox-logo.mp4
$ ffprobe -v error -show_entries stream=codec_name,profile,pix_fmt dosbox-logo.mp4
[STREAM]
codec_name=h264
profile=Constrained Baseline
pix_fmt=yuv420p
[/STREAM]
```
scale=1920:1440:flags=neighbor

With this video filter option, we resize the video to maintain an aspect ratio of 4:3, that is, the aspect ratio of the old CRT computer monitors, so that the output looks similar to how it used to look on those monitors.

The neighbor flag ensures that the nearest-neighbor interpolation (point sampling) is used to decide the colours of the scaled image. Without this option, the default bicubic interpolation algorithm is used. It has the effect of smoothing the edges by introducing new colours such as new shades of grey for this example video. While such smoothing of edges is good for scaling pictures of the real world, in this case, it spoils the crisp and jagged edges that is typical of output visible in DOSBox or the old CRT monitors. With the neighbor option, we retain the crisp and jagged edges visible in the original video capture.
fps=30

This video filter option sets the frame rate to 30 frames per second (FPS). Without this option, the output video has a frame rate of 70.09 FPS and file size of 558 KB. With this option the output frame rate is 30 FPS and the file size is 282 KB.

The default value of machine configuration variable of DOSBox v0.74-3 is svga_s3, so by default it emulates a machine with SVGA card. While emulating a machine with SVGA card, DOSBox creates video capture files with frame rate of 70.09 FPS. When it emulates a machine with CGA card, such as when the its machine configuration variable is set to cga or when DOSBox is run with the -machine cga option, it creates video captures files with frame rate of 59.92 FPS.

For the Logo video capture, there is no high-speed motion going on in the video, so we don't need a high frame rate. A lower frame rate of 30 FPS looks just as good.

DOSBox Audio/Video Capture

The video capture of Digger game is processed similarly, however, there are a few additional things we need to take care of. We want to include the game audio in the output file. We also want a higher frame rate because games may sometimes have high-speed motion.

Like before, we use ctrl+alt+f5 to start capturing the video. The same key combination stops capturing video. The following output appears in the console output to show where the video file is saved:

Capturing Video to /Users/susam/Library/Preferences/capture/digger_000.avi
Stopped capturing video.

Here is the command to convert the video capture of Digger to a distributable format:

ffmpeg -i digger_000.avi -c:a aac -b:a 256k -c:v libx264 -preset veryslow \
       -crf 17 -vf format=yuv420p,scale=1920:1440:flags=neighbor,fps=50 \
       dosbox-digger.mp4

Here is the output:

Video capture of Digger [MP4]

Most of the FFmpeg options used in the command above have been discussed in the previous section. Let us discuss the new options used here that have not been discussed earlier:

-c:a aac

This option selects the native FFmpeg AAC encoder to encode the audio stream to Advanced Audio Coding (AAC) format. It is a very popular format for audio streams in MP4 files.
-b:a 256k

This sets the audio bitrate high enough to ensure that we get good quality audio in the output. We don't need to worry about our specified bitrate being too high. If the audio can be encoded with a lower bitrate without compromising on quality, the output audio stream is encoded at a lower bitrate. For example, for this specific video, the actual audio bitrate in the output file turns out to be 245k because that is enough to encode the audio stream in the input file.
```
$ ffprobe -v error -select_streams a -show_entries stream=bit_rate dosbox-digger.mp4
[STREAM]
bit_rate=245184
[/STREAM]
```
fps=50

If we set the frame rate to a lower value like 30 FPS like we did in the previous section, we still get pretty good output, however, certain parts of the output video look slightly choppy. For example, at 7 seconds into the video when the player is the pushing up against the gold bag, the video becomes slightly choppy if we generate the output with a frame rate of 30 FPS. A higher frame rate such as 50 FPS prevents this problem.

If we omit this option entirely, we get an output video that has the same frame rate as that of the input video, that is, 59.92 FPS, with an output file size of 4.6 MB. With this option, we get an output video that has a frame rate of 50 FPS and a file size of 4.2 MB.

If we look at the output video above closely enough, we see that the colours don't look as crisp as they do in the Digger game screenshot. The neighbor flag was very effective at maintaining the crisp and jagged edges in the Logo video capture but it does not produce perfect results for the Digger video capture in this section. Despite the imperfection, it is still necessary to specify the neighbor option because without this option, the output video looks even worse. We can use a different pixel format like yuv444p instead of yuv420p to work around this issue. Using the yuv444p format indeed results in perfect nearest-neighbour interpolation which helps in retaining the crisp and jagged edges in the video accurately but as explained in the previous section, many media players currently cannot play this pixel format, so we stick to using the yuv420p format in this article.

DOSBox GIF Animation

Now just for fun, let us see if we can convert the video captures into GIF animations. This can be done quite easily with FFmpeg. Here are the commands to convert the Logo video capture to GIF animation:

ffmpeg -i logo_000.avi -vf palettegen palette.png
ffmpeg -i logo_000.avi -i palette.png \
       -lavfi 'scale=1920:1440:flags=neighbor,paletteuse,fps=30' \
       dosbox-logo.gif

The first command generates a colour palette from the video capture. The second command uses this colour palette to generate a GIF animation. Like before, we use the neighbor flag to retain the crisp and jagged edges. Here is the output:

GIF animation of IBM Personal Computer Logo

Here are the commands to convert the Digger video capture to GIF animation:

ffmpeg -i digger_000.avi -vf palettegen palette.png
ffmpeg -i digger_000.avi -i palette.png \
       -lavfi 'scale=1920:1440:flags=neighbor,paletteuse,fps=50' \
       dosbox-digger.gif

GIF animation of a game of Digger

References

Here is a bunch of references that contains more details about the commands used in this article:

Read on website | #dos | #technology | #how-to

FD 100

2019-10-28T00:00:00Z

I learnt how to write computer programs in IBM/LCSI PC Logo. That was back in the year 1992. Computers were much simpler in those days. The ones in our school were IBM PC compatible computers with mostly monochrome displays. The ability to boot a computer using a 5¼-inch floppy disk containing MS-DOS, load a Logo interpreter and then write some programs without any distraction had its own charm that I find missing from modern day computing.

The First Line of Code

The first line of code I ever wrote was:

FD 100

Here is how the output looks:

The first Logo program

That is the 'hello, world' of turtle graphics in Logo. That simple line of code changed my world. I could make stuff happen in an otherwise mostly blank monochrome CRT display. Until then I had seen CRTs in televisions where I had very little control on what I see on the screen. But now, I had control! The turtle became my toy and I could make it draw anything on a 320 × 250 canvas.

Polygons

With a little knowledge of geometry, one could draw polygons. Often the first polygon one would learn to draw was a square. It involves making the turtle walk forward 100 steps, then turn right 90° and repeat these two operations four times in a loop. Here is the code:

REPEAT 4 [FD 100 RT 90]

Here is the output:

A square drawn with IBM Personal Computer Logo

Similarly, one could draw other polygons. The only thing my nine-year-old self then needed to understand was that after drawing an entire polygon, the turtle is back to its original position having completed one full turn. Therefore to draw a polygon with $ n $ sides, the turtle needs to turn by $ 360 / n $ degrees after drawing each side. Drawing a pentagon is as simple as:

REPEAT 5 [FD 80 RT 72]

Here is the output:

A pentagon drawn with IBM Personal Computer Logo

The same approach works for drawing a regular five-pointed star too. The only new thing we need to consider here is that as the turtle draws the shape, it makes two full turns. Therefore, it must turn by $ 720 / 5 $ degrees after drawing each side. Here is the code:

REPEAT 5 [FD 100 RT 144]

Here is the output:

A pentagram drawn with IBM Personal Computer Logo

I remember feeling uneasy about the lopsided appearance of the polygons above and then trying to please my sense of aesthetics by centring these polygons horizontally on the screen and having them stand firmly on an imaginary horizontal line so that they look balanced. I won't include the code and output for that on this page for the sake of brevity of this post but here are links to some screenshots I have kept that show a few of several ways to do it: logo-square-centre.png, logo-pentagon-centre.png and logo-star-centre.png.

Circles

Going from polygons to circles was especially fun. Here is the first piece of code one would normally write to learn to draw a circle:

REPEAT 360 [FD 1 RT 1]

Here is the output:

A circle drawn with IBM Personal Computer Logo

Now precisely speaking, this is not exactly a circle. This is a triacosiahexeacontagon, i.e. a 360-gon. It is an approximation of a circle with 360 very short line segments. Nevertheless it was enough to get a young child who had just begun to learn using the computer excited about programming. It showed me how control flow could be used elegantly to express complex ideas in a simple expression. By the way, here is one way to centre that circle horizontally on the screen: logo-circle-centre.png.

Soon after learning to draw a circle, I learnt to write this:

REPEAT 20 [REPEAT 180 [FD 1 RT 2] RT 18]

This code draws 20 overlapping circles. The output looks like this:

Grid of circles drawn with IBM Personal Computer Logo

A Lasting Effect

There is a lot more to Logo than turtle graphics. Logo gave me a brief taste of functional programming even though back then I did not know the term 'functional programming'. I discovered the same simplicity and elegance in Lisp about 15 years later. After all, Logo can be thought of as a dialect of Lisp without parentheses that controls a turtle.

At an impressionable age of nine, reading and writing code like this and using simple arithmetic, geometry, logic and code to manipulate a two-dimensional world had a lasting effect on me. Back in those days, I used to find joy in sharing some of my interesting Logo programs with my teachers and friends. I like to believe that my passion for software engineering as well as my love for writing code, sharing code and open source development are a result of coming across these beautiful code examples early in my life.

FD 100 – it is a tiny piece of code, but it changed my world!

Read on website | #programming | #dos | #technology

Self-Printing Machine Code

2005-10-27T00:00:00Z

The following 12-byte program composed of pure x86 machine code writes itself to standard output when executed in a DOS environment:

fc b1 0c ac 92 b4 02 cd 21 e2 f8 c3

We can write these bytes to a file with the .COM extension and execute it in DOS. It runs successfully in MS-DOS 6.22, Windows 98, as well as in DOSBox and writes a copy of itself to standard output.

Demo
Quine Conundrums
Proper Quines
A Note on DOS Services
Writing to Video Memory Directly
Boot Program

Demo

On a Unix or Linux system, the following commands demonstrate this program with the help of DOSBox:

echo fc b1 0c ac 92 b4 02 cd 21 e2 f8 c3 | xxd -r -p > foo.com
dosbox -c 'MOUNT C .' -c 'C:\FOO > C:\OUT.COM' -c 'EXIT'
diff foo.com OUT.COM

The diff command should produce no output confirming that the output of the program is identical to the program itself. On an actual MS-DOS 6.22 system or a Windows 98 system, we can demonstrate this program in the following manner:

C:\>DEBUG
-E 100 fc b1 0c ac 92 b4 02 cd 21 e2 f8 c3
-N FOO.COM
-R CX
CX 0000
:C
-W
Writing 0000C bytes
-Q

C:\>FOO > OUT.COM

C:\>FC FOO.COM OUT.COM
Comparing files FOO.COM and OUT.COM
FC: no differences encountered

In the DEBUG session shown above, we use the debugger command E to enter the machine code at offset 0x100 of the code segment. Then we use the N command to name the file we want to write this machine code to. The command R CX is used to specify that we want to write 0xC (decimal 12) bytes to this file. The W command writes the 12 bytes entered at offset 0x100. The Q command quits the debugger. Then we run the new FOO.COM program while redirecting its output to OUT.COM. Finally, we use the FC command to compare the two files and confirm that they are exactly the same.

Let us disasssemble this program now and see what it does. The output below is generated using the Netwide Disassembler (NDISASM), a tool that comes with Netwide Assembler (NASM):

$ ndisasm -o 0x100 foo.com
00000100  FC                cld
00000101  B10C              mov cl,0xc
00000103  AC                lodsb
00000104  92                xchg ax,dx
00000105  B402              mov ah,0x2
00000107  CD21              int 0x21
00000109  E2F8              loop 0x103
0000010B  C3                ret

When DOS executes a program in .COM file, it loads the machine code in the file at offset 0x100 of the code segment chosen by DOS. That is why we ask the disassembler to assume a load address of 0x100 with the -o command line option. The first instruction clears the direction flag. The purpose of this instruction is explained later. The next instruction sets the register CL to 0xc (decimal 12). The register CH is already set to 0 by default when a .COM program starts. Thus setting the register CL to 0xc effectively sets the entire register CX to 0xc. The register CX is used as a loop counter for the loop 0x103 instruction that comes later. Everytime this loop instruction executes, it decrements CX and makes a near jump to offset 0x103 if CX is not 0. This results in 12 iterations of the loop.

In each iteration of the loop, the instructions from offset 0x103 to offset 0x109 are executed. The lodsb instruction loads a byte from address DS:SI into AL. When DOS starts executing this program, DS and SI are set to CS and 0x100 by default, so at the beginning DS:SI points to the first byte of the program. The xchg instruction exchanges the values in AX and DX. Thus the byte we just loaded into AL ends up in DL. Then we set AH to 2 and generate the software interrupt 0x21 (decimal 33) to write the byte in DL to standard output. This is how each iteration reads a byte of this program and writes it to standard output.

The lodsb instruction increments or decrements SI depending on the state of the direction flag (DF). When DF is cleared, it increments SI. If DF is set, it decrements SI. We use the cld instruction at the beginning to clear DF, so that in each iteration of the loop, SI moves forward to point to the next byte of the program. This is how the 12 iterations of the loop write 12 bytes of the program to standard output. In many DOS environments, the DF flag is already in cleared state when a .COM program starts, so the CLD instruction could be omitted in such environments. However, there are some environments where DF may not be in cleared state when our program starts, so it is a best practice to clear DF before relying on it.

Finally, when the loop terminates, we execute the RET instruction to terminate the program.

Quine Conundrums

While reading the description of the self-printing program presented earlier, one might wonder if it is a quine. While there is no standardised definition of the term quine, it is generally accepted that a quine is a computer program that takes no input and produces an exact copy of its own source code as its output. Since a quine cannot take any input, tricks involving reading its own source code or evaluating itself are ruled out.

For example, this shell script is a valid quine:

s='s=\47%s\47;printf "$s" "$s"\n';printf "$s" "$s"

However, the following shell script is not considered a proper quine:

cat $0

The shell script above reads its own source code which is considered cheating. Improper quines like this are often called cheating quines.

Is our 12-byte x86 program a quine? It turns out that we have a conundrum. There is no notion of source code for our program. There would have been one if we had written out the source code of this program in assembly language. In such a case we would first need to choose an assembler and a proper quine would need to produce an exact copy of the assembly language source code (not the machine code bytes) for the chosen assembler. But we are not doing that here. We want the machine code to produce an exact copy of itself. There is no source code involved. We only have machine code. So we could argue that the whole notion of machine code quine is nonsense. No machine code quine can exist because there is no source code to produce as output.

However, we could also argue that the machine code is the input for the CPU that the CPU fetches, decodes and converts to a sequence of state changes in the CPU. If we define a machine code quine to be a machine code program that writes its own bytes, then we could say that we have a machine code quine here.

Let us now entertain the thought that our 12-byte program is indeed a machine code quine. Now we have a new conundrum. Is it a proper quine? This program reads its own bytes from memory and writes them. Does that make it a cheating quine? What would a proper quine written in pure machine code even look like? If we look at the shell script quine above, we see that it contains parts of the executable part of the script code embedded in a string as data. Then we format the string cleverly to produce a new string that looks exactly like the entire shell script. It is a common pattern followed in many quines. The quine does not read its own code but it reads some data defined by the code and formats that data to look like its own code. However, in pure machine code like this the lines between data and code are blurred. Even if we try to keep the bytes we want to read at a separate place in the memory and treat it like data, they would look exactly like machine instructions, so one might wonder if there is any point in trying to make a machine quine that does not read its own bytes. Nevertheless the next section shows how to accomplish this.

Proper Quines

If the thought of a machine code quine program reading its own bytes from the memory makes you uncomfortable, here is an adapation of the previous program that keeps the machine instructions to be executed separate from the data bytes to be read by the program.

fc b3 02 b1 14 be 14 01 ac 92 b4 02 cd 21 e2 f8 4b 75 f0 c3
fc b3 02 b1 14 be 14 01 ac 92 b4 02 cd 21 e2 f8 4b 75 f0 c3

Here is how we can demonstrate this 40-byte program:

echo fc b3 02 b1 14 be 14 01 ac 92 b4 02 cd 21 e2 f8 4b 75 f0 c3 | xxd -r -p > foo.com
echo fc b3 02 b1 14 be 14 01 ac 92 b4 02 cd 21 e2 f8 4b 75 f0 c3 | xxd -r -p >> foo.com
dosbox -c 'MOUNT C .' -c 'C:\FOO > C:\OUT.COM' -c 'EXIT'
diff foo.com OUT.COM

Here is the disassembly:

$ ndisasm -o 0x100 foo.com
00000100  FC                cld
00000101  B302              mov bl,0x2
00000103  B114              mov cl,0x14
00000105  BE1401            mov si,0x114
00000108  AC                lodsb
00000109  92                xchg ax,dx
0000010A  B402              mov ah,0x2
0000010C  CD21              int 0x21
0000010E  E2F8              loop 0x108
00000110  4B                dec bx
00000111  75F0              jnz 0x103
00000113  C3                ret
00000114  FC                cld
00000115  B302              mov bl,0x2
00000117  B114              mov cl,0x14
00000119  BE1401            mov si,0x114
0000011C  AC                lodsb
0000011D  92                xchg ax,dx
0000011E  B402              mov ah,0x2
00000120  CD21              int 0x21
00000122  E2F8              loop 0x11c
00000124  4B                dec bx
00000125  75F0              jnz 0x117
00000127  C3                ret

The first 20 bytes is the executable part of the program. The next 20 bytes is the data read by the program. The executable bytes are identical to the data bytes. The executable part of the program has an outer loop that iterates twice. In each iteration, it reads the data bytes and writes them to standard output. Therefore, in two iterations of the outer loop, it writes the data bytes twice. In this manner, the output is identical to the program itself.

Here is another simpler 32-byte quine based on this approach:

b8 23 09 fe c0 a2 20 01 ba 10 01 cd 21 cd 21 c3
b8 23 09 fe c0 a2 20 01 ba 10 01 cd 21 cd 21 c3

Here are the commands to demostrate this quine:

echo b8 23 09 fe c0 a2 20 01 ba 10 01 cd 21 cd 21 c3 | xxd -r -p > foo.com
echo b8 23 09 fe c0 a2 20 01 ba 10 01 cd 21 cd 21 c3 | xxd -r -p >> foo.com
dosbox -c 'MOUNT C .' -c 'C:\FOO > C:\OUT.COM' -c 'EXIT'
diff foo.com OUT.COM

Here is the disassembly:

$ ndisasm -o 0x100 foo.com
00000100  B82309            mov ax,0x923
00000103  FEC0              inc al
00000105  A22001            mov [0x120],al
00000108  BA1001            mov dx,0x110
0000010B  CD21              int 0x21
0000010D  CD21              int 0x21
0000010F  C3                ret
00000110  B82309            mov ax,0x923
00000113  FEC0              inc al
00000115  A22001            mov [0x120],al
00000118  BA1001            mov dx,0x110
0000011B  CD21              int 0x21
0000011D  CD21              int 0x21
0000011F  C3                ret

This example too has two parts. The first half has the executable bytes and the second half has the data bytes. Both parts are identical. This example sets AH to 9 in the first instruction and then later uses int 0x21 to invoke the DOS service that prints a dollar-terminated string beginning at the address specifed in DS:DX. When a .COM program starts, DS already points to the current code segment, so we don't have to set it explicitly. The dollar symbol has an ASCII code of 0x24 (decimal 36). We need to be careful about not having this value anywhere within the the data bytes or this DOS function would prematurely stop printing our data bytes as soon as it encounters this value. That is why we set AL to 0x23 in the first instruction, then increment it to 0x24 in the second instruction and then copy this value to the end of the data bytes in the third instruction. Finally, we execute int 0x21 twice to write the data bytes twice to standard output, so that the output matches the program itself.

While both these programs take care not to read the same memory region that is being executed by the CPU, the data bytes they read look exactly like the executable bytes. This is what I meant when I mentioned earlier that the lines between code and data are blurred in an exercise like this. This is why I don't really see a point in keeping the executable bytes separate from the data bytes while writing machine code quines.

A Note on DOS Services

The self-printing programs presented above use int 0x21 which offers DOS services that support various input/output functions. In the first two programs, we selected the function to write a character to standard output by setting AH to 2 before invoking this software interrupt. In the next program, we selected the function to write a dollar-terminated string to standard output by setting AH to 9.

The ret instruction in the end too relies on DOS services. When a .COM program starts, the register SP contains 0xfffe. The stack memory locations at offset 0xfffe and 0xffff contain 0x00 and 0x00 respectively. Further, the memory address at offset 0x0000 contains the instruction int 0x20 which is a DOS service that terminates the program. As a result, executing the ret instruction pops 0x0000 off the stack at 0xfffe and loads it into IP. This results in the instruction int 0x20 at offset 0x0000 getting executed. This instruction terminates the program and returns to DOS.

Relying on DOS services gives us a comfortable environment to work with. In particular, DOS implements the notion of standard output which lets us redirect standard output to a file. This lets us conveniently compare the original program file and the output file with the FC command and confirm that they are identical.

But one might wonder if we could avoid relying on DOS services completely and still write a program that prints its own bytes to screen. We definitely can. We could write directly to video memory at address 0xb800:0x0000 and show the bytes of the program on screen. We could also forgo DOS completely and let BIOS load our program from the boot sector and execute it. The next two sections discuss these things.

Writing to Video Memory Directly

Here is an example of an 18-byte self-printing program that writes directly to the video memory at address 0xb800:0x0000.

fc b4 b8 8e c0 31 ff b1 12 b4 0a ac ab e2 fc f4 eb fd

Here are the commands to create and run this program:

echo fc b4 b8 8e c0 31 ff b1 12 b4 0a ac ab e2 fc f4 eb fd | xxd -r -p > foo.com
dosbox foo.com

With the default code page active, i.e. with code page 437 active, the program should display an output that looks approximately like the following and halt:

ⁿ┤╕Ä└1 ▒↕┤◙¼½Γⁿ⌠δ²

Now of course this type of output looks gibberish but there is a quick and dirty way to confirm that this output indeed represents the bytes of our program. We can use the TYPE command of DOS to print the program and check if the symbols that appear in its output seem consistent with the output above. Here is an example:

C:\>TYPE FOO.COM
ⁿ┤╕Ä└1 ▒↕┤
          ¼½Γⁿ⌠δ²
C:\>

This output looks very similar to the previous one except that the byte value 0x0a is rendered as a line break in this output whereas in the previous output this byte value is represented as a circle in a box. This method of visually inspecting the output would not have worked very well if there were any control characters such as backspace or carriage return that result in characters being erased in the displayed output.

A proper way to verify that the output of the program represents the bytes of the program would be to take each symbol from the output of the program, then look it up in a chart for code page 437 and confirm that the byte value of each symbol matches each byte value that makes the program. Here is one such chart that approximates the symbols in code page 437 with Unicode symbols: cp437.html.

Here is the disassembly of the above program:

$ ndisasm -o 0x100 foo.com
00000100  FC                cld
00000101  B4B8              mov ah,0xb8
00000103  8EC0              mov es,ax
00000105  31FF              xor di,di
00000107  B112              mov cl,0x12
00000109  B40A              mov ah,0xa
0000010B  AC                lodsb
0000010C  AB                stosw
0000010D  E2FC              loop 0x10b
0000010F  F4                hlt
00000110  EBFD              jmp short 0x10f

This program sets ES to 0xb800 and DI to 0. Thus ES:DI points to the video memory at address 0xb800:0x0000. DS:SI points to the first instruction of this program by default. Further AH is set to 0xa. This is used to specify the colour attribute of the text to be displayed on screen. Each iteration of the loop in this program loads a byte of the program and writes it along with the colour attribute to video memory. The lodsb instruction loads a byte of the program from the memory address specified by DS:SI into AL and increments SI by 1. AH is already set to 0xa. The value 0xa (binary 00001010) here specifies black as the background colour and bright green as the foreground colour. The stosw instruction stores a word from AX to the memory address specified by ES:DI and increments DI by 2. In this manner, the byte in AL and its colour attribute in AH gets copied to the video memory.

Once again, if you are not happy about the program reading its own executable bytes, we can keep the bytes we read separate from the bytes the CPU executes. Here is a 54-byte program that does this:

fc b3 02 b4 b8 8e c0 31 ff be 1b 01 b9 1b 00 b4
0a ac ab e2 fc 4b 75 f1 f4 eb fd fc b3 02 b4 b8
8e c0 31 ff be 1b 01 b9 1b 00 b4 0a ac ab e2 fc
4b 75 f1 f4 eb fd

Here is how we can create and run this program:

echo fc b3 02 b4 b8 8e c0 31 ff be 1b 01 b9 1b 00 b4 | xxd -r -p > foo.com
echo 0a ac ab e2 fc 4b 75 f1 f4 eb fd fc b3 02 b4 b8 | xxd -r -p >> foo.com
echo 8e c0 31 ff be 1b 01 b9 1b 00 b4 0a ac ab e2 fc | xxd -r -p >> foo.com
echo 4b 75 f1 f4 eb fd | xxd -r -p >> foo.com
dosbox foo.com

With code page 437 active, the output should look approximately like this:

ⁿ│☻┤╕Ä└1 ╛←☺╣← ┤◙¼½ΓⁿKu±⌠δ²ⁿ│☻┤╕Ä└1 ╛←☺╣← ┤◙¼½ΓⁿKu±⌠δ²

We can clearly see in this output that the first 27 bytes of output are identical to the next 27 bytes of the output. Like the proper quines discussed earlier, this one too has two halves that are identical to each other. The executable code in the first half reads the data bytes from the second half and prints the data bytes twice so that the output bytes is an exact copy of all 54 bytes in the program. Here is the disassembly:

$ ndisasm -o 0x100 foo.com
00000100  FC                cld
00000101  B302              mov bl,0x2
00000103  B4B8              mov ah,0xb8
00000105  8EC0              mov es,ax
00000107  31FF              xor di,di
00000109  BE1B01            mov si,0x11b
0000010C  B91B00            mov cx,0x1b
0000010F  B40A              mov ah,0xa
00000111  AC                lodsb
00000112  AB                stosw
00000113  E2FC              loop 0x111
00000115  4B                dec bx
00000116  75F1              jnz 0x109
00000118  F4                hlt
00000119  EBFD              jmp short 0x118
0000011B  FC                cld
0000011C  B302              mov bl,0x2
0000011E  B4B8              mov ah,0xb8
00000120  8EC0              mov es,ax
00000122  31FF              xor di,di
00000124  BE1B01            mov si,0x11b
00000127  B91B00            mov cx,0x1b
0000012A  B40A              mov ah,0xa
0000012C  AC                lodsb
0000012D  AB                stosw
0000012E  E2FC              loop 0x12c
00000130  4B                dec bx
00000131  75F1              jnz 0x124
00000133  F4                hlt
00000134  EBFD              jmp short 0x133

This disassembly is rather long but we can clearly see that the bytes from offset 0x100 to offset 0x11a are identical to the bytes from offset 0x11b to 0x135. These are the bytes we see in the output of the program too.

Boot Program

The 32-byte program below writes itself to video memory when executed from the boot sector:

ea 05 7c 00 00 fc b8 00 b8 8e c0 8c c8 8e d8 31
ff be 00 7c b9 20 00 b4 0a ac ab e2 fc f4 eb fd

We can create a boot image that contains these bytes, write it to the boot sector of a drive and boot an IBM PC compatible computer with it. On booting, this program prints its own bytes on the screen.

On a Unix or Linux system, the following commands can be used to create a boot image with the above program:

echo ea 05 7c 00 00 fc b8 00 b8 8e c0 8c c8 8e d8 31 | xxd -r -p > boot.img
echo ff be 00 7c b9 20 00 b4 0a ac ab e2 fc f4 eb fd | xxd -r -p >> boot.img
echo 55 aa | xxd -r -p | dd seek=510 bs=1 of=boot.img

Now we can test this boot image using DOSBox with the following command:

dosbox -c cls -c 'boot boot.img'

We can also test this image using QEMU x86 system emulator as follows:

qemu-system-i386 -fda boot.img

We could also write this image to the boot sector of an actual physical storage device, such as a USB flash drive and then boot the computer with it. Here is an example command that writes the boot image to the drive represented by the device path /dev/sdx.

cp a.img /dev/sdx

CAUTION: You need to be absolutely sure of the device path of the device being written to. The device path /dev/sdx is only an example here. If the boot image is written to the wrong device, access to the data on that would be lost.

On testing this boot image with an emulator or a real computer, the output should look approximately like this:

Ω♣|  ⁿ╕ ╕Ä└î╚Ä╪1 ╛ |╣  ┤◙¼½Γⁿ⌠δ²

This looks like gibberish, however every symbol in the above output corresponds to a byte of the program mentioned earlier. For example, the first symbol (omega) represents the byte value 0xea, the second symbol (club) represents the byte value 0x05 and so on. The chart at cp437.html can be used to confirm that every symbol in the output indeed represents every byte of the program.

Here is the disassembly of the program:

$ ndisasm -o 0x7c00 boot.img
00007C00  EA057C0000        jmp 0x0:0x7c05
00007C05  FC                cld
00007C06  B800B8            mov ax,0xb800
00007C09  8EC0              mov es,ax
00007C0B  8CC8              mov ax,cs
00007C0D  8ED8              mov ds,ax
00007C0F  31FF              xor di,di
00007C11  BE007C            mov si,0x7c00
00007C14  B92000            mov cx,0x20
00007C17  B40A              mov ah,0xa
00007C19  AC                lodsb
00007C1A  AB                stosw
00007C1B  E2FC              loop 0x7c19
00007C1D  F4                hlt
00007C1E  EBFD              jmp short 0x7c1d
00007C20  0000              add [bx+si],al
00007C22  0000              add [bx+si],al
...

The ellipsis in the end represents the remainder of the bytes that contains zeroes and the boot sector magic bytes 0x55 and 0xaa in the end. They have been omitted here for the sake of brevity.

When a computer boots, the BIOS reads the boot sector code from the first sector of the boot device into the memory at physical address 0x7c00 and jumps to this address. Most BIOS implementations jump to 0x0000:0x7c00 but there are some implementations that jump to 0x07c0:0x0000 instead. Both these jumps are jumps to the same physical address 0x7c00 but this difference poses a problem for us because the offsets in our program depend on which jump the BIOS executed. In order to ensure that our program can run with both types of BIOS implementations, we use a popular trick of having the first instruction of our program execute a jump to address 0x0000:0x7c05 in order to reach the second instruction. This sets the register CS to 0 and IP to 0x7c05 and we don't have to worry about the differences between BIOS implementations anymore. We can now pretend as if a BIOS implementation that jumps to 0x0000:0x7c00 is going to load our program.

The remainder of the program is similar to the one in the previous section. However, there are some small but important differences. While the DOS environment guarantees that AH and CH are initialised to 0 when a .COM program starts, the BIOS offers no such guarantee while loading and executing a boot program. This is why we use the registers AX and CX (as opposed to only AH and CL) in the mov instructions to initialise them. Similarly, while DOS initialises SI to 0x100 when a .COM program starts, for a boot program, we set the register SI ourselves.

If you feel uncomfortable about calling the above program a quine because it reads its own bytes from the memory, we could have the program read the bytes it needs to print from a separate place in memory. We do not execute these bytes. We only read them and copy them to video memory. The following 76-byte program does this:

ea 05 7c 00 00 fc bb 02 00 b8 00 b8 8e c0 8c c8
8e d8 31 ff be 26 7c b9 26 00 b4 0a ac ab e2 fc
4b 75 f1 f4 eb fd ea 05 7c 00 00 fc bb 02 00 b8
00 b8 8e c0 8c c8 8e d8 31 ff be 26 7c b9 26 00
b4 0a ac ab e2 fc 4b 75 f1 f4 eb fd

Here is how we can create a boot image with this:

echo ea 05 7c 00 00 fc bb 02 00 b8 00 b8 8e c0 8c c8 | xxd -r -p > boot.img
echo 8e d8 31 ff be 26 7c b9 26 00 b4 0a ac ab e2 fc | xxd -r -p >> boot.img
echo 4b 75 f1 f4 eb fd ea 05 7c 00 00 fc bb 02 00 b8 | xxd -r -p >> boot.img
echo 00 b8 8e c0 8c c8 8e d8 31 ff be 26 7c b9 26 00 | xxd -r -p >> boot.img
echo b4 0a ac ab e2 fc 4b 75 f1 f4 eb fd | xxd -r -p >> boot.img
echo 55 aa | xxd -r -p | dd seek=510 bs=1 of=boot.img

Here are the commands to test this boot image:

dosbox -c cls -c 'boot boot.img'
qemu-system-i386 -fda boot.img

The output should look like this:

Ω♣|  ⁿ╗☻ ╕ ╕Ä└î╚Ä╪1 ╛&|╣& ┤◙¼½ΓⁿKu±⌠δ²Ω♣|  ⁿ╗☻ ╕ ╕Ä└î╚Ä╪1 ╛&|╣& ┤◙¼½ΓⁿKu±⌠δ²

Here is the disassembly of this program:

$ ndisasm -o 0x7c00 boot.img
00007C00  EA057C0000        jmp 0x0:0x7c05
00007C05  FC                cld
00007C06  BB0200            mov bx,0x2
00007C09  B800B8            mov ax,0xb800
00007C0C  8EC0              mov es,ax
00007C0E  8CC8              mov ax,cs
00007C10  8ED8              mov ds,ax
00007C12  31FF              xor di,di
00007C14  BE267C            mov si,0x7c26
00007C17  B92600            mov cx,0x26
00007C1A  B40A              mov ah,0xa
00007C1C  AC                lodsb
00007C1D  AB                stosw
00007C1E  E2FC              loop 0x7c1c
00007C20  4B                dec bx
00007C21  75F1              jnz 0x7c14
00007C23  F4                hlt
00007C24  EBFD              jmp short 0x7c23
00007C26  EA057C0000        jmp 0x0:0x7c05
00007C2B  FC                cld
00007C2C  BB0200            mov bx,0x2
00007C2F  B800B8            mov ax,0xb800
00007C32  8EC0              mov es,ax
00007C34  8CC8              mov ax,cs
00007C36  8ED8              mov ds,ax
00007C38  31FF              xor di,di
00007C3A  BE267C            mov si,0x7c26
00007C3D  B92600            mov cx,0x26
00007C40  B40A              mov ah,0xa
00007C42  AC                lodsb
00007C43  AB                stosw
00007C44  E2FC              loop 0x7c42
00007C46  4B                dec bx
00007C47  75F1              jnz 0x7c3a
00007C49  F4                hlt
00007C4A  EBFD              jmp short 0x7c49
00007C4C  0000              add [bx+si],al
00007C4E  0000              add [bx+si],al
...

This program has two identical halves. The first half from offset 0x7c00 to offset 0x7c25 are executable bytes. The second half from offset 0x7c26 to 0x7c4b are the data bytes read by the executable bytes. The executable part of the code has an outer loop that uses the register BX as the counter variable. It sets BX to 2 so that the outer loop iterates twice. In each iteration, it reads data bytes from the second half of the program and prints them. The code to read bytes and print them is very similar to our earlier program. Since the data bytes in the second half are identical to the executable bytes in the first half, printing the data bytes twice amounts to printing all bytes of the program.

While this program does avoid reading the bytes that the CPU executes, the data bytes look exactly like the executable bytes. Although I do not see any point in trying to avoid reading executable bytes in an exercise like, this program serves as an example of a self-printing boot program that does not execute the bytes it reads.

Read on website | #assembly | #programming | #dos | #technology

Rebooting With JMP Instruction

2003-03-02T00:00:00Z

While learning about x86 microprocessors, I realised that it is possible to reboot a computer running MS-DOS or Windows 98 by jumping to the memory address FFFF:0000. Here is an example DEBUG.EXE session from MS-DOS 6.22:

C:\>DEBUG
G =FFFF:0000

In the above example, we start the DOS debugger and then enter the G (go) command to execute the program at FFFF:0000. Just doing this simple operation should reboot the system immediately.

When the computer boots, the x86 microprocessor starts in real mode and executes the instruction at FFFF:0000. This is an address in the BIOS ROM that contains a far jump instruction to go to another address, typically F000:E05B.

C:\>DEBUG
-U FFFF:0000 4
FFFF:0000 EA5BE000F0    JMP     F000:E05B

The address F000:E05B contains the BIOS start-up program which performs a power-on self-test (POST), initialises the peripheral devices, loads the boot sector code and executes it. These operations complete the booting sequence.

The important point worth noting here is that the very first instruction the microprocessor executes after booting is the instruction at FFFF:0000. We can use this fact to create a tiny executable program that can be used to reboot the computer. Of course, we can always perform a soft reboot using the key sequence ctrl+alt+del. However, just for fun, let us create a program to reboot the computer with a JMP FFFF:0000 instruction.

Reboot Program

Here is a complete DEBUG.EXE session that shows how we could write a simple reboot program:

C:\>DEBUG
-A
1165:0100 JMP FFFF:0000
1165:0105
-N REBOOT.COM
-R CX
CX 0000
:5
-W
Writing 00005 bytes
-Q

C:\>

Note that the N (name) command specifies the name of the file where we write the binary machine code to. Also, note that the W (write) command expects the registers BX and CX to contain the number of bytes to be written to the file. When the DOS debugger starts, it already initialises BX to 0 automatically, so we only set the register CX to 5 with the R CX command above.

Now we can execute this 5-byte program like this:

C:>REBOOT

Debugger Scripting

In the previous section, we saw how we can start DEBUG.EXE and type the debugger commands and the assembly language instruction to jump to FFFF:0000. We can also keep these debugger inputs in a separate text file and feed that to the debugger. Here is how the content of such a text file would look:

A
JMP FFFF:0000

N REBOOT.COM
R CX
5
W
Q

If the above input is saved in a file, say, REBOOT.TXT, then we can run the DOS command DEBUG < REBOOT.TXT to assemble the program and create the binary executable file. The following DOS session example shows how this command behaves:

C:\>DEBUG < REBOOT.TXT
-A
1165:0100 JMP FFFF:0000
1165:0105
-N REBOOT.COM
-R CX
CX 0000
:5
-W
Writing 00005 bytes
-Q

C:>

Disassembly

Here is a quick demonstration of how we can disassemble the executable code:

C:\>DEBUG REBOOT.COM
-U 100 104
117C:0100 EA0000FFFF    JMP     FFFF:0000

While we did not really need to disassemble this tiny program, the above example shows how we can use the debugger command U (unassemble) to translate machine code to assembly language mnemonics.

Programming With DOS Debugger

2003-02-11T00:00:00Z

Introduction

MS-DOS as well as Windows 98 come with a debugger program named DEBUG.EXE that can be used to work with assembly language instructions and machine code. In MS-DOS version 6.22, this program is named DEBUG.EXE and it is typically present at C:\DOS\DEBUG.EXE. On Windows 98, this program is usually present at C:\Windows\Command\Debug.exe. It is a line-oriented debugger that supports various useful features to work with and debug binary executable programs consisting of machine code.

In this post, we see how we can use this debugger program to assemble a few minimal programs that print some characters to standard output. We first create a 7-byte program that prints a single character. Then we create a 23-byte program that prints the "hello, world" string. All the steps provided in this post work well with Windows 98 too.

Introduction
Print Character
Hello, World
Debugger Scripting
Disassembly
INT 20 vs RET
Conclusion

Print Character

Let us first see how to create a tiny 7-byte program that prints the character A to standard output. The following DEBUG.EXE session shows how we do it.

C:\>DEBUG
-A
1165:0100 MOV AH, 2
1165:0102 MOV DL, 41
1165:0104 INT 21
1165:0106 RET
1165:0107
-G
A
Program terminated normally
-N A.COM
-R CX
CX 0000
:7
-W
Writing 00007 bytes
-Q

C:\>

Now we can execute this program as follows:

C:\>A
A
C:\>

The debugger command A creates machine executable code from assembly language instructions. The machine code created is written to the main memory at address CS:0100 by default. The first three instructions generate the software interrupt 0x21 (decimal 33) with AH set to 2 and DL set to 0x41 (decimal 65) which happens to be the ASCII code of the character A. Interrupt 0x21 offers a wide variety of DOS services. Setting AH to 2 tells this interrupt to invoke the function that prints a single character to standard output. This function expects DL to be set to the ASCII code of the character we want to print.

The command G executes the program in memory from the current location. The current location is defined by the current value of CS:IP which is CS:0100 by default. We use this command to confirm that the program runs as expected.

Next we prepare to write the machine code to a binary executable file. The command N is used to specify the name of the file. The command W is used to write the machine code to the file. This command expects the registers BX and CX to contain the number of bytes to be written to the file. When the DOS debugger starts, BX is already initialised to 0, so we only set the register CX to 7 with the R CX command. Finally, we use the command Q to quit the debugger and return to MS-DOS.

Hello, World

The following DEBUG.EXE session shows how to create a program that prints a string.

C:\>DEBUG
-A
1165:0100 MOV AH, 9
1165:0102 MOV DX, 108
1165:0105 INT 21
1165:0107 RET
1165:0108 DB 'hello, world', D, A, '$'
1165:0117
-G
hello, world

Program terminated normally
-N HELLO.COM
-R CX
CX 0000
:17
-W
Writing 00017 bytes
-Q

C:\>

Now we can execute this 23-byte program like this:

C:\>HELLO
hello, world

C:\>

In the program above we use the pseudo-instruction DB to define the bytes of the string we want to print. We add the trailing bytes 0xD and 0xA to print the carriage return (CR) and the line feed (LF) characters so that the string is terminated with a newline. Finally, the string is terminated with the byte for dollar sign ('$') because the software interrupt we generate next expects the string to be terminated with this symbol's byte value.

We use the software interrupt 0x21 again. However, this time we set AH to 9 to invoke the function that prints a string. This function expects DS:DX to point to the address of a string terminated with the byte value of '$'. The register DS has the same value as that of CS, so we only set DX to the offset at which the string begins.

Debugger Scripting

We have already seen above how to assemble a "hello, world" program in the previous section. We started the debugger program, typed some commands and typed assembly language instructions to create our program. It is also possible to prepare a separate input file with all the debugger commands and assembly language instructions in it. We then feed this file to the debugger program. This can be useful while writing more complex programs where we cannot afford to lose our assembly language source code if we inadvertently crash the debugger by executing an illegal instruction.

To create a separate input file that can be fed to the debugger, we may use the DOS command EDIT HELLO.TXT to open a new file with MS-DOS Editor, then type in the following debugger commands and then save and exit the editor.

A
MOV AH, 9
MOV DX, 108
INT 21
RET
DB 'hello, world', D, A, '$'

N HELLO.COM
R CX
17
W
Q

This is almost the same as the inputs we typed into the debugger in the previous section. The only difference from the previous section is that we omit the G command here because we don't really need to run the program while assembling it, although we could do so if we really wanted to.

Then we can run the DOS command DEBUG < HELLO.TXT to assemble the program and create the binary executable file. Here is a DOS session example that shows what the output of this command looks like:

C:\>DEBUG < HELLO.TXT
-A
1165:0100 MOV AH, 9
1165:0102 MOV DX, 108
1165:0105 INT 21
1165:0107 RET
1165:0108 DB 'hello, world', D, A, '$'
1165:0117
-N HELLO.COM
-R CX
CX 0000
:17
-W
Writing 00017 bytes
-Q

C:\>

The output is in fact very similar to the debugger session in the previous section.

Disassembly

Now that we have seen how to assemble simple programs into binary executable files using the debugger, we will now briefly see how to disassemble the binary executable files. This could be useful when we want to debug an existing program.

C:\>DEBUG A.COM
-U 100 106
117C:0100 B402          MOV     AH,02
117C:0102 B241          MOV     DL,41
117C:0104 CD21          INT     21
117C:0106 C3            RET

The debugger command U (unassemble) is used to translate the binary machine code to assembly language mnemonics.

C:\>DEBUG HELLO.COM
-U 100 116
117C:0100 B409          MOV     AH,09
117C:0102 BA0801        MOV     DX,0108
117C:0105 CD21          INT     21
117C:0107 C3            RET
117C:0108 68            DB      68
117C:0109 65            DB      65
117C:010A 6C            DB      6C
117C:010B 6C            DB      6C
117C:010C 6F            DB      6F
117C:010D 2C20          SUB     AL,20
117C:010F 776F          JA      0180
117C:0111 726C          JB      017F
117C:0113 64            DB      64
117C:0114 0D0A24        OR      AX,240A
-D 100 116
117C:0100  B4 09 BA 08 01 CD 21 C3-68 65 6C 6C 6F 2C 20 77   ......!.hello, w
117C:0110  6F 72 6C 64 0D 0A 24                              orld..$

INT 20 vs RET

Another way to terminate a .COM program is to simply use the instruction INT 20. This consumes two bytes in the machine code: CD 20. While producing the smallest possible executables was not really the goal of this post, the code examples above indulge in a little bit of size reduction by using the RET instruction to terminate the program. This consumes only one byte: C3. This works because when a .COM file starts, the register SP contains FFFE. The stack memory locations at offset FFFE and FFFF contain 00 and 00 respectively. Further, the memory address offset 0000 contains the instruction INT 20. Here is a demonstration of these facts using the debugger program:

C:\>DEBUG HELLO.COM
-R SP
SP FFFE
:
-D FFFE
117C:FFF0                                            00 00
-U 0 1
117C:0000 CD20          INT     20

As a result, executing the RET instruction pops 0000 off the stack at FFFE and loads it into IP. This results in the instruction INT 20 at offset 0000 getting executed which leads to program termination.

While both INT 20 and RET lead to successful program termination both in DOS as well as while debugging with DEBUG.EXE, there is some difference between them which affects the debugging experience. Terminating the program with INT 20 allows us to run the program repeatedly within the debugger by repeated applications of the G debugger command. But when we terminate the program with RET, we cannot run the program repeatedly in this manner. The program runs and terminates successfully the first time we run it in the debugger but the stack does not get reinitialised with zeros to prepare it for another execution of the program within the debugger. Therefore when we try to run the program the second time using the G command, the program does not terminate successfully. It hangs instead. It is possible to work around this by reinitialising the stack with the debugger command E FFFE 0 0 before running G again.

Conclusion

Although the DOS debugger is very limited in features in comparison with sophisticated assemblers like NASM, MASM, etc., this humble program can perform some of the basic operations involved in working with assembly language and machine code. It can read and write binary executable files, examine memory, execute machine instructions in memory, modify registers, edit binary files, etc. The fact that this debugger program is always available with MS-DOS or Windows 98 system means that these systems are ready for some rudimentary assembly language programming without requiring any additional tools.

Editing Binaries in DOS

2002-07-18T00:00:00Z

Both MS-DOS and Windows 98 come with a debugger program named DEBUG.EXE that make it possible to edit binary files without requiring additional tools. Although the primary purpose of this program is to test and debug executable files, it can be used to edit binary files too. Two examples of this are shown in this post. The first example edits a string of bytes in an executable file. The second one edits machine instructions to alter the behaviour of the program. Both examples provided in the next two sections can be reproduced on MS-DOS version 6.22. These examples can be performed on Windows 98 too after minor adjustments.

Editing Data

Let us first see an example of editing an error message produced by the MODE command. This DOS command is used for displaying and reconfiguring system settings. For example, the following command sets the display to show 40 characters per line:

C:\>MODE 40

The following command reverts the display to show 80 characters per line:

C:\>MODE 80

Here is another example of this command that shows the current settings for serial port COM1:

C:\>MODE COM1

Status for device COM1:
-----------------------
Retry=NONE

C:\>

An invalid parameter leads to an error like this:

C:\>MODE 0

Invalid parameter - 0

C:\>

We will edit this error message to be slightly more helpful. The following debugger session shows how.

C:\>DEBUG C:\DOS\MODE.COM
-S 0 FFFF 'Invalid parameter'
117C:19D1
-D 19D0 19FF
117C:19D0  13 49 6E 76 61 6C 69 64-20 70 61 72 61 6D 65 74   .Invalid paramet
117C:19E0  65 72 0D 0A 20 0D 0A 49-6E 76 61 6C 69 64 20 6E   er.. ..Invalid n
117C:19F0  75 6D 62 65 72 20 6F 66-20 70 61 72 61 6D 65 74   umber of paramet
-E 19D0 12 'No soup for you!' D A
-D 19D0 19FF
117C:19D0  12 4E 6F 20 73 6F 75 70-20 66 6F 72 20 79 6F 75   .No soup for you
117C:19E0  21 0D 0A 0A 20 0D 0A 49-6E 76 61 6C 69 64 20 6E   !... ..Invalid n
117C:19F0  75 6D 62 65 72 20 6F 66-20 70 61 72 61 6D 65 74   umber of paramet
-N SOUP.COM
-W
Writing 05C11 bytes
-Q

C:\>

We first open MODE.COM with the debugger. When we do so, the entire program is loaded into offset 0x100 of the code segment (CS). Then we use the S debugger command to search for the string "Invalid parameter". This prints the offset at which this string occurs in memory.

We use the D command to dump the bytes around that offset. In the first row of the output, the byte value 13 (decimal 19) represents the length of the string that follows it. Indeed there are 19 bytes in the string composed of the text "Invalid parameter" and the following carriage return (CR) and line feed (LF) characters. The CR and LF characters have ASCII codes 0xD (decimal 13) and 0xA (decimal 10). These values can be seen at the third and fourth places of the second row of the output of this command.

Then we use the E command to enter a new string length followed by a new string to replace the existing error message. Note that we enter a string length of 0x12 (decimal 18) which is indeed the length of the string that follows it. After entering the new string, we dump the memory again with D to verify that the new string is now present in memory.

After confirming that the edited string looks good, we use the N command to specify the name of the file we want to write the edited binary to. This command starts writing the bytes from offset 0x100 to the named file. It reads the number of bytes to be written to the file from the BX and CX registers. These registers are already initialised to the length of the file when we load a file in the debugger. Since we have not modified these registers ourselves, we don't need to set them again. In case you do need to set the BX and CX registers in a different situation, the commands to do so are R BX and R CX respectively.

Finally, the W command writes the file and the Q command quits the debugger. Now we can test the new program as follows:


C:\>SOUP 0

No soup for you! - 0

C:\>

Editing Machine Instructions

In this section, we will see how to edit the binary we created in the previous section further to add our own machine instructions to print a welcome message when the program starts. Here is an example debugger session that shows how to do it.

C:\>DEBUG SOUP.COM
-U
117C:0100 E99521        JMP     2298
117C:0103 51            PUSH    CX
117C:0104 8ACA          MOV     CL,DL
117C:0106 D0E1          SHL     CL,1
117C:0108 32ED          XOR     CH,CH
117C:010A 80CD03        OR      CH,03
117C:010D D2E5          SHL     CH,CL
117C:010F 2E            CS:
117C:0110 222E7D01      AND     CH,[017D]
117C:0114 2E            CS:
117C:0115 890E6402      MOV     [0264],CX
117C:0119 59            POP     CX
117C:011A 7505          JNZ     0121
117C:011C EA39E700F0    JMP     F000:E739
-D 300
117C:0300  07 1F C3 18 18 18 18 18-00 00 00 00 00 00 00 00   ................
117C:0310  00 00 FF 00 00 00 00 00-FF 00 00 00 00 00 00 00   ................
117C:0320  00 00 00 00 00 00 00 00-00 00 FF FF 90 00 40 00   ..............@.
117C:0330  00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00   ................
117C:0340  00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00   ................
117C:0350  00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00   ................
117C:0360  00 00 00 FF 00 00 00 00-00 00 00 00 00 00 00 00   ................
117C:0370  02 00 2B C0 8E C0 A0 71-03 A2 BA 07 A2 BC 07 3C   ..+....q.......<
-A
117C:0100 JMP 330
117C:0103
-A 330
117C:0330 MOV AH, 9
117C:0332 MOV DX, 33A
117C:0335 INT 21
117C:0337 JMP 2298
117C:033A DB 'Welcome to Soup Kitchen!', D, A, '$'
117C:0355
-W
Writing 05C11 bytes
-Q

C:\>

At the beginning, we use the debugger command U to unassemble (disassemble) some bytes at the top of the program to see what they look like. We see that the very first instruction is a jump to offset 0x2298. The debugger command D 300 shows that there are contiguous zero bytes around offset 0x330. We replace some of these zero bytes with new machine instructions that print our welcome message. To do this, we first replace the jump instruction at the top with a jump instruction to offset 0x330 where we then place the machine code for our welcome message. This new machine code prints the welcome message and then jumps to offset 0x2298 allowing the remainder of the program to execute as usual.

The debugger command A is used to assemble the machine code for the altered jump instruction at the top. By default it writes the assembled machine code to CS:0100 which is the address at which DOS loads executable programs. Then we use the debugger command A 330 to add new machine code at offset 0x330. We try not to go beyond the region with contiguous zeroes while writing our machine instructions. Fortunately for us, our entire code for the welcome message occupies 37 bytes and and the last byte of our code lands at offset 0x354.

Finally, we write the updated program in memory back to the file named SOUP.COM. Since the debugger was used to load the file named SOUP.COM, we do not need to use the N command to specify the name of the file again. When a file has just been loaded into the debugger, by default the W command writes the program in memory back to the same file that was loaded into the memory.

Now our updated program should behave as shown below:

C:\>SOUP COM1
Welcome to Soup Kitchen!

Status for device COM1:
-----------------------
Retry=NONE

C:\>SOUP 0
Welcome to Soup Kitchen!

No soup for you! - 0

C:\>

That's our modified program that prints a welcome message and our own error message created with the humble DOS debugger.

Susam's DOS Pages

Good Quality DOSBox Video Capture

Vintage DOS Programs

Contents

Software Versions

IBM PC Logo in DOSBox

Digger in DOSBox

DOSBox Screenshot Capture

DOSBox Video Capture

DOSBox Audio/Video Capture

DOSBox GIF Animation

References

FD 100

The First Line of Code

Polygons

Circles

A Lasting Effect

Self-Printing Machine Code

Contents

Demo

Quine Conundrums

Proper Quines

A Note on DOS Services

Writing to Video Memory Directly

Boot Program

Rebooting With JMP Instruction

Reboot Program

Debugger Scripting

Disassembly

Programming With DOS Debugger

Introduction

Contents

Print Character

Hello, World

Debugger Scripting

Disassembly

INT 20 vs RET

Conclusion

Editing Binaries in DOS

Editing Data

Editing Machine Instructions