[Oberon] Portability of Project Oberon

[Jörg]

Wojtek

I generally agree that NW‘s low level sources are full of double declarations (e.g stack-size literals at two different places etc) and literals instead of named constants. I cleaned them up a little, eg. my Modules imports Kernel.

Your effort of collecting all low level values and document them in one file is appreciated. But ONE big SysDef.Mod is NOT a good idea. Oberon modules are unlike .h files in C not just „includes“; Oberon modules have version keys.
So when you mix graphic-related constants, register-related constants and memory-related constants in one place, the whole Oberon idea of separate compilation is void.
When you change e.g the stack size in your SysDef, SysDef gets a new key. Hence you would have to recompile the graphic driver without any need to do so.

The way out would be to spilt up your SysDef in several modules, eg MemoryDef, RegisterDef and so on.
Further on, we should carefully decide whether to export a CONST or a VAR (or even a PROCEDURE). NW often uses VARs (iso CONST) as then the upper modules don‘t have to be recompiled if the value changes.
Those considerations are always a trade off of portability and code efficiency. I know you rate portability high. The higher you go in the abstraction, the more I like portability as well. The lower HW-based you go, code efficiency is key and decides whether your code is fast enough to detect a signal edge or not. On lower layers portability is anyhow questionable as HW might differ.

br
Jörg

> Am 08.12.2020 um 07:00 schrieb Skulski, Wojciech <skulski at pas.rochester.edu>:
> 
> Paul wrote:
> 
>> I would love to see Oberon running on all these hardware platforms, so that users can choose the hardware appropriate to the specific task to be accomplished.
> 
> OK. In the following I am only interested in the FPGA Oberon because of my instrumentation focus. I am not talking of A2, LNO, etc. Only the FPGA and only RISC5.
> 
> Note that I am saying "portability" rather than "porting". We are not porting anything yet. I rather want to assess the ability to get ported. In other words, is the technology ready to get ported, and what are the obstacles.
> 
> OK, lets take it from the top. IMHO, portability has three aspects. (1) The platform to be ported to. (2) Technology to be ported. (3) The community. 
> 
> 1) The platform. There was some desire to find the perfect board. It appears there is no such board. I want to say two things. 
> 
> 1.1) A perfect board will never exist. There will be always something missing for some applications. So rather than looking for a perfect board, we should get the technology ready to get ported to any board. Let's invest in the technology to make it portable. 
> 
> 1.2) The perfect board actually does exist. It is called "the emulator". It is cheap in production (zero cost to clone). After some learning, more persons will be able to modify the emulator than those who can build a physical board. The boards can be designed after the emulator work is completed. So the "perfect board" problem actually has an acceptable solution.
> 
> 2) The technology. Lets look at the present, and what can be done to improve portability.
> 
> 2.1) At present the FPGA Oberon System is poorly portable, what can surprise some of you. I will discuss this assessment based on my release on github. I attached three files in PDF. Not everyone has BlackBox. 
> 
> 2.1.1) The List_of_SysDef_Files is telling you the files which need to get ported if SysDef was NOT AVAILABLE. It is a surprisingly long list. Someone may want to dispute the details, but this is secondary. The take home is "if you want to port by hand, fishing for all the hardcoded numbers and addresses, then it is going to be tough". On the other hand, SysDef is a single file. Port this file and your work is mostly done. Lots of testing will remain, but you do not need to go for a long fishing expedition as I had to do.
> 
> 2.1.2) Now look at the actual code file, with and without SysDef. You will see that the numbers (in red) are not just at the beginning, but also at the end. Why "12", why "24"? If you overlook such booby traps then your porting effort will likely blow up. Now look at the other file. I put some serious effort into pointing out the mines and to comment what they mean. More comments are in the SysDef file itself (attached). If you read the SysDef file then you will not be in total darkness.
> 
> 2.1.3) You will now understand why I  used color while fishing for the Easter Eggs. B/W text is Easter Egg friendly. The syntax coloring will not help either. I was not fishing for murky syntax. I was fishing for booby traps.
> 
> 2.2) What can be done to improve portability? This work is showing what needs to be done. Porting a single file is much easier than trying to port more than a dozen files.
> 
> 2.3) This needs to continue. I am proposing to continue factoring out all the literal numbers, adding comments, and identifying the low level interfaces which are essential for porting. 
> 
> 2.4) Notice that Oberon System has THREE interfaces rather than one. One interface is official and well publicized. It is the IMPORT interface. The other two interfaces are less discussed. Yet these are the ones crucial for porting. These two interfaces need be exposed, documented, and collected in a definition file or files. 
> 
> 2.4.1) The 1st interface is REGISTERS which interface with hardware. (Firmware is hardware, so no need to differentiate.) Below is an example of a single register to show you the present status quo. 
> 
> 2.4.1.1) Example: The following constants represent the SAME object, namely the millisecond counter: FFFFFFC0, 03FFFFC0, 0, -64. All these numbers are used in various places to denote the same object. It is one of the Easter Eggs. 
> 
> 2.4.2) The 2nd interface are in-memory locations of stack, heap, video, and many others. When you encounter 80000H in the code, do you know what it is doing in the particular place? If you encounter "24", do you know what this memory location is doing? This is crucial to know if you need to add or reduce the memory, or to change the frame buffer. If you change the wrong 80000H, or put a wrong number into address "24", the system will blow up. So all such numbers scattered in the code are potential booby traps. 
> 
> 2.4.3) Look at SysDef.Mod where I collected many booby traps, but probably not all. Some probably still remain in the code. They need to be removed and documented to aid portability.
> 
> 3) Community. The last problem is "who wants to accept the portable OS"? Lack of acceptance is probably the biggest obstacle to develop portable FPGA Oberon System.
> 
> Thanks,
> W.
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> <List_of_SysDef_Files.odc.pdf>
> <BootLoadLine_no_SysDef.odc.pdf>
> <BootLoadLine_with_SysDef.Mod.odc.pdf>
> <SysDef_Feb_11_2020c.Mod.odc.pdf>
> --
> Oberon at lists.inf.ethz.ch mailing list for ETH Oberon and related systems
> https://lists.inf.ethz.ch/mailman/listinfo/oberon