[openfirmware] Porting OFW to custom hardware

[Mitch Bradley]

R&D4 wrote:
>
> Hi all,
>
> we are currently porting OFW to a custom board (codename Neptune) with 
> is much like OLPC, but without SuperIO and keyboard controller.
>
> First of all: is there any documentation about how to add a new custom 
> platform? As a beginner I just copied lxdevel directory to one called 
> neptune, changed some definitions inside:
> * Makefile
> * neptune.bth (taken from lxdevel.bth)
> * config.fth
>
> Is this correct?

That's a good start.
>
> Of couse, it's a bit hard for me to figure out, for example, where to 
> look for some basic initialization (e.g. PLL, SDRAM, memory mapping).

I assume you are using the version that I checked in yesterday, that 
removes the olpc dependencies from the lxdevel build.  If not, switch to 
that version.  It will be much easier to work with.

The PLL init is in "rmstart.fth" - that is "real mode start", which is 
the first thing that executes after power on.  Its job is to get the 
system into 32-bit mode as fast as possible.  On the Geode, where you 
have to double-reset to program the PLL, the PLL init is also in that 
file.  In principle, PLL init could be in the 32-bit mode code, but it 
is faster to do it in rmstart .  Executing code prior to PLL setup is 
inherently very slow, so I minimized the number of instructions executed 
prior to PLL turn-on.

The next code that executes is in romreset.bth .  It runs in 32-bit 
mode.  Its job is to get the memory working, again as quickly as 
possible.  What the means in practice is that any system setup that 
isn't necessary for memory controller setup is deferred until later.

The one exception is the serial port - I typically turn that on very 
early in romreset.fth, so debugging is possible.

There is a difference between OLPC and the lxdevel board in the area of 
serial port init.  OLPC uses the serial port inside the 5536 chip, 
whereas the lx devel board has an external superio.   If you look at 
cpu/x86/pc/olpc/romreset.bth, you will see some 5536 UART init code 
starting at line 76.  (\ Init UART ...  [ifndef] lxdevel).  If you are 
using the 5536 UART, you'll want to include that code in your romreset.bth

After romreset.bth sets up the memory controller, it includes 
dev/geode/draminit.fth , which configures the SDRAM chips themselves.

At the bottom of draminit.fth, commented out with "0 [if] .. [then]", 
there is a very simple memory test that just writes a couple of data 
patterns to a RAM location.  It's not a complete memory test, but is 
usually sufficient to tell if the memory is working at all.  It won't 
detect misconfiguration of the bank layout registers.  Change "0 [if]" 
to "1 [if]" to enable it.

Once the RAM is turned on, romreset.bth includes cpu/x86/pc/resetend.fth 
.  resetend.fth is generic for all x86 PC platforms; independent of 
either the Geode CPU or to the platform's I/O setup.  Its purpose is to 
do final setup of the memory management unit (GDT and possibly page 
tables), then load the Forth dictionary into RAM.  That loading process 
involves either copying or inflating the Forth dictionary from ROM into RAM.

resetend.fth's final action is to jump to the RAM copy of the Forth 
dictionary.  Forth then runs an initialization chain named 
"stand-init".  Debugging that is easy because you can use the Forth 
debugger to step through it.

>
> AFAIK the "official" documentation is here:
>
> http://www.firmworks.com/open_firmware/literature/
>
> among these documents is there also a guide for porting OFW or about 
> OFW "internals"? ("Open Firmware Command Reference" seems the closest 
> to my needs)

We did a porting guide for an ARM platform, but we haven't done one for 
x86.   The command reference has a lot of useful information that is 
machine independent.  There is also a manual for how to write FCode 
drivers.  It explains how the device interface works.
>
> Thanks in advance and Best Regards,
>