Creating Boot Files for EO with Astrobe for RISC5

General discussions about using the Astrobe IDE to program the FPGA RISC5 cpu used in Project Oberon 2013
Post Reply
gray
Posts: 109
Joined: Tue Feb 12, 2019 2:59 am
Location: Mauritius

Creating Boot Files for EO with Astrobe for RISC5

Post by gray » Wed Apr 14, 2021 11:16 am

The following applies to Embedded Oberon, running on an FPGA board, using an SD card for storage.

To venture into making changes to the inner core of the Embedded Oberon (EO) system, that is, modifying modules Files, FileDir, Modules, or Kernel, it's necessary to create a new boot file to reflect the changes. The boot file contains a pre-linked binary of these four modules, and it needs to be written to the boot area of the local disk. Upon reset, the RISC5 CPU will start to execute the boot loader (stored in the PROM of the FPGA) which will first load the boot file, and then branch to address 0, which on an unmodified EO system, and upon a cold start, holds the address of the body of Modules. Later in the startup sequence the address of the abort handler will be put at address 0 (cf. 14.1. The Startup Process on the Project Oberon book, accessible via Astrobe > Help > Project Oberon).

Creating a modified boot file can be done in Embedded Oberon, using the Astrobe IDE. The following assumes an unmodified EO system, and with the caveat that it works for me and OMM. Just make an SD card backup as recommended below, and you should be safe. ;) Before you write out the new boot file, no potentially destructive changes are made to the system.

Andreas Pirklbauer has created and graciously made available a whole suite of tools for that purpose:

<https://github.com/andreaspirklbauer/Ob ... ding-tools>

For this exercise here, you only need to download file ORL.Mod from the Sources/FPGAOberon2013 folder. ORL.Mod is the boot linker/loader to first create the boot file, and then write it to the SD card. On Windows with Astrobe, do not change the line endings of the file as described on Andreas' GitHub page.

Depending on how your Oberon system is structured, ORL.Mod can be put where-ever it makes sense, eg. with the system files, or with the application programs. The compiler just needs to find modules SYSTEM, Kernel, Files, Modules, Texts, and Oberon.

ORL.Mod uses three references that don't exists on EO, namely Texts.OpenWriter, Texts.Append, and Oberon.Log. The two procedures and the log variable are only involved in text output, but not required for the correct functioning of the tool. Texts.OpenWriter is not needed for EO's console output to work, as all text output is hard-wired to the Astrobe terminal, and EO does not have a Log, so the easiest solution is to simply comment the corresponding calls out in ORL.Mod. They appear only in a few places.

After that, ORL.Mod compiles in the Astrobe IDE.

Now upload ORL.rsc, Files.rsc, FileDir.rsc, Modules.rsc, and Kernel.rsc to the SD card with the Astrobe IDE serial uploader. Note that if you ever have re-compiled the inner core modules, ie. created new '.rsc' files, make sure they are consistent among each other (see also below). If you had created new '.smb' files, you'd have been in trouble before, or you don't need to read further, as you already know how to create a boot file. :)

From the Astrobe terminal, execute

Code: Select all

ORL.Link Modules ~
This creates the boot file with the four pre-linked modules, named 'Modules.bin'.

At this point it would be a very good idea to back up your SD card.

Then execute

Code: Select all

ORL.Load Modules.bin ~
This writes 'Modules.bin' to the boot area of the SD card.

Reboot your system, and if all went well, everything works as before, and you don't see a difference. But now you're ready to make changes to the four inner core modules, to compile and upload them, and to create and install a new boot file by simply executing the two commands in the Astrobe terminal.

In case the system does not boot on the first attempt, make sure the inner core modules are consistent by building Modules in the Astrobe IDE. Restore the SD card from the backup you just made, upload any changes, and run the two commands above again.

The safest way to ensure consistency of the inner core is to build, not just compile, module Modules. Any file that needs uploading thereafter will be right at the top of the file list, if sorted by Date modified. If you'll make changes to the inner core module interfaces, also rebuild the modules of the outer core. It should suffice to build module System on EO. Of course any programs that import inner core modules would also need to be rebuilt. As a general rule, I always use build, not just compile. Astrobe's build system is a stroke of genius to selectively compiling exactly the needed modules.

If you want to quickly check if all works, and changes to the inner core actually "make it through" to the boot file, make this change to the body of Modules:

Code: Select all

BEGIN LED(0FFH); Init; Load("Oberon", M);
  LED(res); REPEAT UNTIL FALSE  (*only if load fails*)
END Modules.
That is, add 'LED(0FFH)' right at the beginning after BEGIN. Now follow the above steps, ie. build Modules, upload Modules.rsc, and execute the ORL.Link and ORL.Load commands. The system should boot, and you'll see all system LEDs on for a short time.

To taste my own dog food, I have modified the boot loader, and modules Kernel and Modules, to finally make the stack size configurable, not any more hard-coded to 08000H, by following the above steps. A potentially useful feature for embedded system with little memory, or with different working modes, eg. with coroutines that each have their own stack, usually somewhere in module space. Works OMM. Yes, I dutifully made my backups. :) I'll report more details on this on the forum later.

Andreas has a comprehensive documentation for all the tools he makes available, for all kinds of situations and configurations, and including lots of very helpful additional information. Worth a read!

cfbsoftware
Site Admin
Posts: 493
Joined: Fri Dec 31, 2010 12:30 pm
Contact:

Re: Creating Boot Files for EO with Astrobe for RISC5

Post by cfbsoftware » Sun Oct 24, 2021 10:27 pm

A big thank you to gray for documenting this process. Creating a new boot file for Embedded Oberon has now got a whole lot easier with the new Link command in v8.0 Astrobe for RISC5. The new process is this:

1. Update the core modules (FileDir, Kernel, Files and Modules) with your changes as required.
2. Run the Astrobe Project > Build menu command to ensure that all the object modules (*.rsc) that are affected by your changes are recompiled.
3. Display Modules.Mod as the current module in the Astrobe editor and run the Astrobe Project > Link menu command.

You will see the following messages:

Code: Select all

Astrobe for RISC5 Linker v8.0.0
Loading: Modules
Loading: Files
Loading: Kernel
Loading: FileDir
Link completed. File created: Modules.bin
4. Upload Modules.bin and any *.rsc files (other than the four core modules) created in step 2 to your FPGA board.
5. Run the Embedded Oberon command BootFile.Load to replace the existing bootfile on the board's SD card.
6. Restart the Embedded Oberon system to use the new boot file.

NOTE: It is advisable to make a backup copy of your SD card before staring this process ;) If the Oberon system fails to restart you can restore the earlier working system from the backup copy that you made, until you have determined what the problem is.

Post Reply