Creating Boot Files for EO with Astrobe for RISC5
Posted: 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
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
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:
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!
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 ~
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 ~
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.
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!