[Oberon] RiskFive; was Oberon on ULX3S explanation

[Andreas Pirklbauer]

    > My favorite lines of code in Modules.Mod are:
    >
    >        mno := inst DIV 100000H MOD 10H;
    >        pno := inst DIV 1000H MOD 100H;
    >        disp := inst MOD 1000H;
    >       ....
    >       SYSTEM.PUT(adr, (offset MOD 1000000H) + 0F7000000H);

This particular piece of code is actually documented in section "6.3. The linking loader” on p.83 of the book Project Oberon, in a paragraph that starts with "At the very end of the file three integers called fixorgP, fixorgD, and fixorgT are read”.

But of course, this is a rather sparse “documentation” indeed. A reader not already intimately familiar with the (source code of the) compiler and the associated fixup code in the module loader (Modules.Load) will - based on this description alone - not immediately have the idea to

a) search for “fixorgP” in the code generator module ORG, where he would find the following line in ORG.Call

   Put3(BL, 7, ((-x.r) * 100H + x.a) * 1000H + pc-fixorgP); fixorgP := pc-1

with Put3 as follows

   code[pc] := ((op+12) * 10H + cond) * 1000000H + (off MOD 1000000H); INC(pc)

b) then “know” or “remember” that -x.r in an item x for a procedure is in fact the the module number (mno) and x.a is in fact the entry number for the procedure (pno)

c) deduce from ORG.Call and ORG.Put3 that..

  the 4 bits [20..23]  = -x.r (= the module number, mno)
  the 8 bits [12..19]  =  x.a (= the entry number for the procedure, pno) 
  the 12 bits [0..11]  =  pc-fixorgP (= the displacement between 2 instructions the fixup chain)

d) and finally realize that these lines, of course, correspond one-to-one to the following lines in Modules.Load

  mno := inst DIV 100000H MOD 10H;
  pno := inst DIV 1000H MOD 100H;
  disp := inst MOD 1000H;

Of course, once you explain all this, every student will go “ah right, this all makes sense. of course. easy."

But the truth is that all of the above requires one to be already familiar with the source code of both the compiler and the loader.

So for people who "live and breathe” the (source code of the) compiler and loader on a daily basis, it’s all obvious and not all that hard.

But for someone reading the code for the first time - or students -  it’s rather steep hurdle indeed.

I have lamented about this in the past. Educators will have cheat sheets..

-ap