What is the Emulator of the FPGA Oberon System Doing?
Synopsis. An emulator is a complete environment whose display looks like the physical display of the real FPGA Oberon System, but it executes in a window under a regular PC (Windows, Linux, or Mac). The emulator enables Oberon System software development without having access to the actual FPGA board.
Motivation.
An emulator is a cost and time effective alternative to building the actual FPGA boards. The Oberon emulators are available for free. Last, but not least, the emulator installed on the developer's laptop can travel much more easily than the actual board with its monitor, mouse, and keyboard.
Background information. The presently available FPGA Oberon System emulators provide software representations of the original FPGA Oberon System developed with the Digilent Spartan-3 Starter Kit. They implement the same memory map and the same set of peripherals, with minor variations. (E.g., the wireless network is not available.) The emulators execute the actual RISC5 code. It means, that the code targeting the FPGA board can be developed, compiled, and tested under the emulator. The emulators provide the same graphics display as the original board. It means that graphical applications can be developed and tested under the emulator.
Is the SD card disk image needed or not? The actual FPGA Oberon System uses an SD card for its file system. (I will devote an entire page to this topic.) The emulators differ how they emulate the Oberon FS. Some emulators use an binary ISO file which can be then copied to the SD card "as is". It is convenient if you want to transfer your work to the actual board. Some other emulators use the host directory to store the files. It is convenient if all your work is performed within the emulator. Some emulators allow to swich between both approaches. It may not be the most convenient solution if it requires to modify the emulator itself.
Can you copy external files to the emulator? Yes. Each emulator comes with the instructions or examples how to do it.
Can you use an actual SD card with the emulator? I do not know yet. It would be quite convenient if the SD card could be used directly, using a USB card reader. Newer laptops are equipped with the SD slot, so you would not even need an extra reader.
Can you upgrade the Oberon System software within the emulator? Yes. Each emulator comes with the installed set of the Oberon System files, which usually are the original files (sometimes they are newer). You can upgrade the entire System by copying over these files. It means that you can use the newest set of Oberon System files under any emulator. You can also add your own files. The burden of archiving your work is then on you.
A hint. A very effective way of archiving your work is to zip the SD Card image (if used) or the working PC directory (if used) and archive the zipped image on a network storage or in the cloud. It allows to archive the entire project, including the compiled binary files. Tools like git or SVN are not very good at storing the binary files.
Caveats. Since the emulators implement the original FPGA Oberon System, testing new firmware or hardware additions is not possible without modifying the emulator. I do not know yet how easy or how difficult it would be to dive into the emulators' guts to implement the modifications. I presume that it strongly depends on how a given emulator was structured.
Summary. The FPGA Oberon System emulator will let you develop Oberon code for the FPGA board at zero upfront cost, without using the actual hardware. The emulator will let you develop the high level code, such a compiler or graphics, and then test it within the emulated RISC5 environment. The emulator is executing the RISC5 binary code using the software rendition of the RISC5 processor. After testing, the code can be transferred to the actual board. The drawback of an emulator is that adding new emulated firmare or hardware can be hard. Particular emulators may require vastly different effort to implement new firmware or hardware emulation.
Emulator under QEMU by Charles Perkins
Available from github. It is heavy duty stuff. The screen shot looks very impressive. The name risc6 was coined by Charles to avoid confusion with RISC-V, which QEMU is also supporting. The list of topics on the parent page looks very promising.
Caveat: The status is probably reflected in the following passage from the risc6 README.md: "The target qemu-system-risc6 has been succesfully compiled on Linux and on OSX. It should also be possible to compile it on Windows with some effort." The key words are "some effort". I dunno. I listed this project in order not to miss something important.
Emulator on the Mac by Roel P. de Jong
Free from the Apple Apps store. No SD card disk image is needed. The Oberon files are stored in a Mac folder. It is a faithful rendition of the original FPGA Oberon System with the B/W display. Recommended by Joerg, who is using it as his main development tool.
Caveat: This emulator is named Oberon Core in the Apple store. However, Oberon Core is also a name of a large community effort in Russia, whose goal is further development of the Component Pascal after it has been released to the public domain. Their online library of Oberon books and papers can be of interest to many Oberon developers. The two Oberon Cores have nothing to do with each other. Beware of a possible confusion!
Emulator on Windows, OS X, and Linux by Peter de Wachter
Available from github. Windows executable is provided. Other versions need be built by the user. It works off the SD card disk image, which can be downloaded from the github. The Oberon files are stored inside the image. It is a faithful rendition of the original FPGA Oberon System with the B/W display. The color display is not supported. Andreas is using it to develop the Extended Oberon System.
Caveat: Andreas distributes his own SD card image, which you can download from his github site. I presume his disk image is reflecting his new developments described in the EOS_news. If this is the first time you are installing the Extended Oberon, it will be prudent to compare the content of the SD image against the EOS news. Later down the road you only need to overwrite those files which have been mentioned in the EOS news. Do not rely on the file creation dates because Andreas always overwrites ALL his files.
Tools for building the disk image are available from the Norebo repository. Open that page and look for the heading PO2013 image build tools. According to the description, the provided command will download the project sources, compile them, and create runnable disk image for the Peter de Wachter's emulator. The same image should also run under the Michael Schierl's emulator described next.
Peter's Emulator Modified by Michael Schierl
Available from github. Windows executable is provided. Other versions need be built by the user. It is a fork of the previous emulator, modified by adding a 4-bit color display and a possibility of using the host directory to store files. Some minor tweaks are needed to activate either feature. The github web page looks almost like the PDW page, which may be confusing. This emulator can presumably be used with the Extended Oberon System.
Peter's Emulator Ported to Go by Frederik Zipp
Available from github.
There are two variants:
1) cmd/oberon-emu: A pure Go version which starts a server that uses WebSockets to communicate with a web browser HTML canvas as a display as well as for keyboard and mouse input.
2) cmd/oberon-emu-sdl: A version based on Cgo+SDL, which requires libsdl2 development files to build.
Frederick also ported Niklaus Wirth’s Project Oberon RISC compiler to Go.
Go version of the N.Wirth Oberon-07 compiler.
Online Emulator in JavaScript by Colby Russell
This emulator is very similar to the online emulators by Michael Schierl, described below. Unlike Michael's emulators, this one is a single file which you can load into the browser. It will display a title bar and the pulldown menu with the option to load the disk image. The format must be the same as the PDW format. However, the disk content must be patched in the same way, as it is required by the Michael's JS emulator described below. The emulator was announced to the Oberon mailing list. The posting provided the links to the emulator's file. I downloaded this file by right-clicking and saving to disk. The links are below.
As of July/28/2020, there seem to be no disk images in the PDW format with the patched content. The original PDW images do not open with this emulator. They would need to get "patched". The patched images wrapped into the PNG format do not open either, because thy are not in the PDW format. We need an AND of both features. No such images are available yet.
Three Emulators by Michael Schierl
The following web page links to three different emulators described in the next two sections. The first one was written in Java, the next one in JavaScript, and the last one in JavaScript + WebAssembly. Note that they do not emulate Java or Javascript, but rather they emulate Oberon running on the RISC5 processor.
Either one of the two online emulators can be started by pressing the solitary Start button. It will execute the code in the same browser window, overwriting the calling page. The two online emulators are very similar, but the actual code is different. One uses the JavaScript engine, while the other uses WebAssembly. If you want to download the code (as opposed to running it in a browser), then the sources are available from github. Both the JS and JS+WebAssembly sources are packed into the same ZIP archive which you can download. I actually received them directly from Michael packed into the file OberonEmulator-gh-pages.zip. You can download the same from github. Explore the content and you will find sources for both the online emulators.
It is a bit confusing that the names of Michael's web locations are so similar. In fact they serve two different roles. One is a source repository, while the other one is starting the online emulator in your browser.
An Offline Emulator in Java by Michael Schierl
The first emulator written in Java is described here. It is an offline executable.
The offline "Java emulator" can be downloaded and installed on your host computer like a regular application. It comes with the set of SD disk images, including Extended Oberon (still named "experimental" on the page). You can either download the images, or build them yourself (the last bullet on the page). The SD images bundled with this emulator are updated less frequently than the images bundled with the JS emulator. Michael suggested that the Java emulator is a bit out of his focus.
Unlike the online JS tools (next sections), both the Java application and the disk image(s) will be present on your host. The file modifications will thus survive between the sessions without any special precautions.
Two Online Emulators by Michael Schierl
One online emulator was written in JavaScript, the other in JavaScript+WebAssembly. Unlike the offline emulators, the online emulator runs in the browser window.
Open the access page to all three emulators:
Project Oberon emulator in JavaScript and Java.
Some Q&A concerning the online JS emulators.
From the emulator to the local storage: Run "PCLink1.Run" inside the emulator. Then you can write a file name or more than one in the Transfer checkbox and click Copy to transfer the files out of the emulator. They will be handled like downloads in your browser, so probably stored in your Downloads folder.
From the local storage to the emulator: Click "Import file..." and select one or more files to send them into the emulator. You can also drag & drop onto the field Import file... if your browser supports drag & drop.
A convenience feature: In case any file name imported ends with ".txt", the ".txt" will get stripped and the file will be converted to Oberon Text. Convenient to add many files from Prof. Wirth's website at once..
Answer: When you enable "Autosave" (check mark), the file will be stored in your browser's local storage automatically (your browser may ask for permission when you click it the first time). Otherwise, the modified disk image may get lost when you close the session. It depends on whether your browser performs a cleanup after closing a window. It is an option of the web browser (not of the emulator!).
Answer: See above. Either you transfer it manually from the emulator to local storage, or enable Autosave.
Answer: Unfortunately not. The online emulator does not talk to the local SD card reader, where you can plug your SD card.
Answer: Yes, but with caveats. The online emulator does not read the full image used by the FPGA Oberon. It uses a simplified disk image format, which was optimized for the web. Your images need to be prepared to work with the online emulator. If they are prepared, you can use them with the emulator.
Answer: First, the images are stripped of the FS information natively used by the Oberon System. For example, the leading (first) SD partition is removed. Then the images are coded using the PNG format and named with the .png extension. They can actually be opened with IrfanView. (But they do not look very impressive after opening.) Using the PNG format enables transmission of the binary, non-ASCII content "behind the scenes" without resorting to ASCII HEX coding. Since the PNG format uses a built-in compression, and the extra information has been stripped, the images are quite small. E.g., the largest image DebuggableDiskImage.png is 870 kB. Others are even smaller.
Second, there are some patches to the Oberon System run time, described in Creating images for the JS Oberon Emulator.
1. The Oberon System low level processing gets optimized to make the System more suitable to run under the JS in a browser, where high CPU load cannot be tolerated. Most of these tweaks look like excellent candidates for the actual OS running on the actual board, where extra CPU cycles are always good to optimize away to conserve power.
2. JavaScript runs in a sandbox in your browser. JS has no access to the hardware. In particular, JS cannot access the physical SD card. In principle it could access the image of the SD card like the other emulators are doing (e.g., the PDW emulator). But these images cannot be downloaded from the remote website, because some browsers disallow downloading of binary files by JS code. (Probably because of security.) Packing the images into the PNG format is solving this problem, at the expense of making the PNG disk image different from the original SD card image. Consequently, the low level disk access drivers had to change.
3. Breaking news! I heard from Michael that the JS emulator can access the original image format. Such an image cannot be served over the remote web (because transmission is not allowed), but it can be served locally. The JS emulator can automatically recognize the format of the image, either original or PNG. If it is given the original format, then it can save it as a PNG image. The reverse operation is not supported (yet???). Life would be easier if the conversion could be performed both ways.
Answer: The pedestrian method consists of copying the files from the "prepared" image to a local directory. Then you need to copy them either into the native Oberon SD card image, or to the FPGA board.
1. The former has to be done with another local emulator because no other software but the emulators can work with those images. On this occasion you may also test the code under this other emulator. Note that the compilers need be either the same or at least compatible between both emulators. E.g., you should avoid using the Extended Oberon compiler with one, and the Classic Wirth compiler with the other emulator.
2. Copying to the FPGA board is accomplished as usual with the serial link.
Answer: Load the "prepared" SD disk image to the emulator (see the next question). Save the current (maybe modified) SD disk image to a local directory. Automatically save the current SD disk image in a local directory, so you do not accidentally lose it after closing the session.
Answer: It does not travel too far. It is stored on your local computer, on your own disk. (So the word "upload" is an oxymoron.) The same is true with the images selected from Michael's web site. They get transferred to your local disk, just like regular PNG files. (The web browser thinks that they are graphics.) You are then using either Michael's disk image, or your own, residing on your own disk. Make sure that these files are not erased when you close the session. Various options described above help avoid losing the files.
Hint: If you closed the session by accident, the most recent SD disk image may still reside in a temporary directory of your computer (using Michael's PNG format). Search the web cache directory for this PNG file, if you know where it is.
Answer: Start a second emulator in second browser window. Both emulators are connected via serial link. (At that point PCLink and file transfer between either emulator and the host is no longer available.)
1. Keep in mind that you cannot modify the disk images on Michael's website. However, you can run this emulator on your own web server, using your own images. Once you get a clear picture how to do it, you can clone Michael's website and use the clone on your own.
2. The most compact solution could be to run the web server locally on your own machine, and to connect to that server locally. The role of the web browser is then reduced to a local graphical display. The JS code will be compiled on the fly by the webserver.
3. Since most good ideas have already been invented, Michael has described it under this link. Scroll to the bottom, and read his recommendation.
1. Download the online emulator from github in a ZIP archive.
2. Unpack the ZIP into the webserver directory on your webserver (e.g., your laptop).
3. Figure out how to serve the website to yourself or to the local network.
4. Serve the website. It is complete with both online emulators and the disk images.
5. Prepare your own disk images and copy them into the webserver directory, so you can use them.
6. Modify the config.json startup file to show these new images in the menu.
1. No need to build any executable.
2. You do not need to learn how to use C on Windows.
3. The web browser is both displaying graphics and compiling the JS code.
4. The previous bullet is true if you do not use WebAssembly. It offers no advantage. See the next section.
1. Preparing the disk images may be tedious.
2. The Oberon System running under the JS emulator is not identical to the one running on the board.
3. You need to undo the "preparations" before transfering the source back to the board.
Remarks on Michael's Online Emulators
When I was looking for a suitable emulator to be modified (adjusted, ported) to my own projects, which involve building new FPGA boards with new peripherals, I was grossly surprised how little code there is in Michael's online emulators. Their structure seems pretty clear. Both the small size and good structure look promising for porting.
Michael explained to me, that both the JS and JS+WA emulators are roughly on par. The CPU emulation code in the WASM version is split among two files. The JS source is ~140 lines and the WASM source is ~300 lines. The CPU emulation code in the pure JS version is in one file with ~400 lines. All other code is the same (which is probably the reason why they are distributed in the same archive).
According to Michael, WASM does not really have any benefits in emulating the screen or the other peripherals. For executing the WASM version in the browser, you need to compile the WASM source code, which results in about 2.5 kB of compiled WASM. The pure JS version is easier to modify since you do not need to compile it after you modify the code.
Concerning the download size over the web, the WASM version is about 5 kB less, which roughly matches the difference of the
WASM source size and the compiled WASM size. This is negligible when compared with the disk image which you also need to download to start the session (hundreds of kilobytes).