Debugging Open Firmware Startup

These are notes about debugging early Open Firmware startup on XO-1.75 and XO-4 laptops.

Requirements

The following applies to XO-1.75 and XO-4 laptops. Your mileage may vary on earlier XOs (they don't have a CForth interpreter, for example).

You will need a terminal attached to the host serial console on the laptop.

Early Error Codes

During the early boot process, CForth initializes a tiny frame buffer in SRAM and uses it to display error codes on the display. In a normal boot, all you see is a flash of white. But if something goes wrong early on, a large blocky two-digit number will be displayed.

Most of those numbers come from OFW - they correspond to the "Msg #: 41" numbers seen when compiling OFW. CForth kicks off the process but OFW follows up. CForth is responsible for making the numbers visible if you press check during the boot process or if OFW doesn't take over the display within 8 seconds.

CForth

You can interrupt the boot process in CForth to reconfigure the memory timings or number of memory controllers, or as a prelude to interrupting the Open Firmware startup process.

CForth is a simple Forth interpreter which runs on a small ARM processor (the Security Processor) separate from the main processor cores in the Armada 610 and PXA2128 SoCs. It is the core which executes first during a system boot, and which boots Open Firmware (and hence Linux) on the other processor cores. A detailed explanation is avaliable in the Forth Lessons.

If you hold down the rotate key while booting the system, CForth does not proceed to automatically boot Open Firmware and instead sits at an interactive prompt. While it is possible to reconfigure the memory options or change the SoC operating frequency while in CForth, we are generally just interested in progressing to Open Firmware. Type "ofw" and hit return while again holding down the rotate key. This should place you in OFW's interactive mode.

Keeping CForth Around

When you start OFW, CForth typically releases control of the main console UART, but continues to run on the security processor, interpreting keyboard and mouse input for the system. If debugging a nasty problem, it is sometimes useful to keep CForth communicative in order to examine the state of the machine after the main processor hangs.

Instead of typing "ofw", type:

dbg ofw

In this case, Open Firmware will be started but CForth will continue to communicate over the second serial console. This second serial console may be used to monitor internal SoC registers, examine memory, etc., while the main processor boots Open Firmware followed by Linux.

Running at different speeds

CForth sets the operating frequency of the SoC, based on a GPIO. You can see the function called at:

ok see late-init

It is possible to run at other frequencies. Functions for running at 800 MHz, 1 GHz, and 1.2 GHz are built in. To run at a particular speed, type:

ok setup-thermal
ok set-frequency-800m
ok init-dram ofw

To instead run at 1.2 GHz, try:

ok setup-thermal
ok set-frequency-1.2g
ok init-dram ofw

Those functions live in app/arm-xo-cl4/clockset.fth.

Open Firmware

By holding down the rotate key, you are entering Open Firmware before it has initialized any of the laptop (such as the display!). CForth has already initialized the SoC pin functions, and the memory. Open Firmware has initialized the Forth interpreter, but hasn't start loading any device drivers.

At this point, there are two OFW routines called which tend to run into trouble: stand-init and startup. You can walk through them using the OFW debugging features. Start with:

debug startup resume

And if that starts debugging after the problem has already happened, try:

debug stand-init resume

Enjoy!