hintron / 8086-toolchain

Assembler, Compiler and Emulator targeting the 8086 platform for use on x86 architecture. For BYU ECEn 425 - RTOS

8086 Toolchain

This is the C-based 8086 toolchain for BYU ECEn 425 (Real Time Operating Systems). This repo also includes an archive of the class website, including all the homework, labs, documentation, and lectures from the class.

The toolchain was taken directly from /ee2/ee425/src/dist on the BYU CAEDM computers.

Disclaimer: For ECEn 425 projects, this may or may not compile exactly the same as the CAEDM machines

Build and Install

To clone this repo, do:

$ cd ~
$ git clone https://github.com/hintron/8086-toolchain.git

Prerequisites to build toolchain:

• Linux:

  • On Debian based systems (Ubuntu, etc.), run the following in your terminal: sudo apt-get install gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev xterm
  • Tested on Ubuntu 16.04 x86_64, Ubuntu 17.04 x86_64, Ubuntu 17.10, and Ubuntu 22.04 (regular and WSL)

• Mac OS X:

  • Your system will depend on the X11 Window system, which is now called XQuartz. It can be found here.
  • Tested with XQuartz 3.7.7 on Mac OS X Yosemite.

Building on Linux/Mac:

cd into the cloned repo and run make:

$ cd ~/8086-toolchain/
$ make

This will create 5 binaries in the ./bin/ directory:

• c86 - The 8086 compiler
• emu86 - The 8086 emulator
• nasm - The 8086 assembler
• ndiasm - The 8086 disassembler
• ProgramCRT - The terminal program used by emu86 to display Simptris.

If there are any problems, you can try cding into each of the tool directories and running make individually so you can see the warnings/errors more clearly.

To use the binaries from anywhere, see Setting Your Path below.

Setting Your Path

To use the binaries from anywhwere, modify your PATH at the bottom of your ~/.profile or ~/.bashrc (or whatever your shell's startup script is):

# 8086 Toolchain
export PATH="$HOME/8086-toolchain/bin":$PATH

Reload your shell's startup by either closing your shell and reopening it, or using the source command:

source ~/.profile
# Or
source ~/.bashrc

This will add your toolchain bin to PATH in the current terminal.

Common Problems

Linux:

• cdefs not defined: Make sure Linux prereqs are installed
• Parsing errors with Perl generated headers/macros: At some point the files were saved with 'DOS' line endings instead of Unix, so if you see a ^M (Windows carriage return char) that is likely the issue and saving (or overwriting) the file correctly should fix it. Make sure to blow away any generated files.
• If on Ubuntu 17.04 or higher, you may get the following error: xterm: cannot load font '-misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso10646-1'. emu86 will still work fine. If you wish to fix the error, you can try following the steps in this form: http://forum.porteus.org/viewtopic.php?f=53&t=1013

Mac:

• cpp does not remove // comments correctly: See Makefile example below, make sure to add -xc++ flag to cpp to remove c99 style comments.

Makefile Example

lab1.bin:       lab1final.s
                nasm lab1final.s -o lab1.bin -l lab1.lst  # Step 4, Assemble

lab1final.s:    clib.S lab1asm.S lab1.s
                cat clib.S lab1asm.S lab1.s > lab1final.s # Step 3, Concatenate

lab1.s:         lab1.c
                cpp -xc++ lab1.c lab1.i    # Step 1, Preprocess
                c86 -g lab1.i lab1.s       # Step 2, Compile

clean:
                rm lab1.bin lab1.lst lab1final.s lab1.s lab1.i

test:
                emu86 lab1.bin

Makefile error: If you copy this directly and paste into a Makefile, the tabs will often be converted to spaces. You will get a "Missing separator" error from make. Just replace the indentions with two tabs and it should work.

Website

The ECEn 425 website is stored in directory website/ and contains lab instructions, 8086 resources, homework assignments, and class slides.

Browsing the website

The class website is currently hosted via GitHub pages here. The original site is also available on Wayback Machine.

Optionally, you can browse all the files locally by pointing your web broswer to the file website/index.html, and all the links should work.

Another option is to host the website locally. In a terminal, do:

cd website/
python3 -m http.server 8000

Then, access the local website in your browser at localhost:8000. This option is nice because it allows Chrome extensions (like DarkReader) to work (Chrome extensions are not allowed to run on local file paths).

Updating the website hosted by GitHub pages

To update the class website hosted by GitHub pages, first install the ghp-import Python module:

pip install ghp-import

Then, simply run scripts/gh-pages-import.sh. This will overwrite the gh-pages branch of this repo with the current contents of the website/ directory.

Website history

After Dr. Archibald retired in August 2020, the BYU ECEn department discontinued ECEn 425. At some point in 2022, BYU also stopped hosting the original class website. Luckily, the class website was archived by Wayback Machine, and the website was saved to this repo on 2023-05-03 using this tool.

8086-toolchain's Issues

emu86: Enable running script of emu86 commands on startup

I get really tired of inputting the same commands in over and over to get into the debugging state that I want. Unfortunately, there is no way currently to script emu86, as any shell IO indirection only seems to execute the first command, and then input is frozen.

So I propose adding a -s <script-file> argument to emu86, where it executes each line as an emu86 command once emu86 is started. It should support # and // comments, ignore empty lines, and the emulator output should look and act exactly as if the user typed it in directly via the terminal.

emu86 already has an undocumented <file> argument that will implicitly call l <file> on startup, so that shows us the path we need to take to do this.

This will enable creating scripts to easily enter the state we want, without manually typing things. These scripts can then be saved off and used for automated tests and for debugging.

emu86: Script comments turn into command if line larger than `COMMAND_BUFFER_SIZE`

When a commented line in a script is longer than COMMAND_BUFFER_SIZE, then fgets() will split the line up. The second half of the line will then be interpreted as the next command.

I need a way to ignore each call to fgets() until there is a newline detected. Once a newline is detected, then I can process the next line like normal.

emu86: Fix special key commands

Currently, on Ubuntu or WSL Ubuntu, any time an arrow key is pressed, emu86 freezes and all further input is disabled.

The code shows that GetCommandString() originally could handle up/down arrow keys to navigate command history (as well as ctrl+n and ctrl+p aliases), esc to clear the current command input, and backspace to delete a character from the current input.

I'm not sure how long it's been broken. I seem to remember it working when I took and TA'd the class, but I don't think I've seen it work on Ubuntu 22.04.

(I need to check that my cumulative tweaks to emu86 didn't break this somehow.)

Currently, the reason it's frozen is because it gets in an infinite loop, I think with

while(extendedKeyPress()) getchar();

I wonder if extendedKeyPress() is to blame, and I wonder if there was something new in Ubuntu 22.04 that broke some of this old terminal stuff.

`exit()` needs to be able to force the simulator itself to return the exit code

It's not enough to just print that the program exited - we need the simulator itself to exit with that same return code if we want to be able to create scriptable regressions.

Don't display welcome message by default

I find the first 4 lines printed out when starting emu86 to be a bit annoying. I think I want to hide that by default, but add an option to print it out. Or, just get rid of it entirely, since the emu86 binary itself now already has a help message.

Create GitHub Pages for the website

GitHub pages should be able to host the class website, since it's all static. That would make it easy to reference the website and not have to spin up a local webserver to view the contents.

Create ability for emu86 to "poke out" values

It would be nice if there was an emu86 command that could "poke" a value out of the emulator to a file or stdout or something. This would enable emu86 to talk to regression tests directly.

I'm envisioning a way to set up regressions for simptris on various seeds, run each of them until Game Over, and confirm that the correct score has been reached.

Note that the "score" variable currently doesn't match the score inside the simptris emulator. So I would also want a way to get that real value from the emulator itself.

emu86: unbounded `e` command doesn't work when no stdin is available

I'm trying to set up regression tests to run on the Git pre-commit hook. The problem is that the hook is not an interactive shell, so stdin is disabled/points to nothing. This messes up with the e command, though the e N command seems to work just fine. The symptoms of e are that nothing is printed to the debug terminal and the program hangs indefinitely.

Create `-c` argument for inline commands

Instead of supplying an entire file of commands via the -s argument, it may be more convenient (for e.g. regression tests) to have a -c <commands> argument. <commands> could be as simple as e or perhaps include multiple ;-separated commands, like l artoss.bin; simptris; e.

Spaces in `-c <command_string>` seem to cause issues

This works fine:

emu86 -c "l artoss.bin;z;simptris;e"

while this causes an error:

$ emu86 -c "l artoss.bin;z;simptris; e"
Emu86>l artoss.bin
File "artoss.bin" loaded at address 0000:0000 (CS:IP -> 0000:0100).
Emu86>z
Hard exit mode enabled.
Emu86>simptris
Simptris mode enabled.
Emu86> e
Invalid number of instructions: "tris"