Andrew Rutz's blog

OBP debug #1

This is my first in a hopeful series of blogs regarding debugging at the OBP (OpenBoot Prom) level.

OBP is the system firmware that executes after POST (Power-On Self-Test) and before (in the normal case) Solaris. (Note that another Client of OBP is the kernel debugger, kmdb. In that case, kmdb would be loaded, and then transition control to Solaris)

---

One can either intentionally or unintentionally arrive at OBP's prompt. It is affectionately known as the "OK prompt":

ok 

To intentionally arrive at the OK prompt, one can use a command sequence such as

# sync; sync
# halt

or

# init 0

or

# shutdown -i0 -y -g0

(The above command says to go to run-level zero and give a grace period of zero seconds).

Unintentional transfer of control to the OK prompt can be caused by traps un-/mis-handled by Solaris.

---

To load the OBP commands (eg, Forth words) that are specific to Solaris debugging, one needs to tell the Solaris boot code to load the forthdebug module. One does this by adding this to the /etc/system file and rebooting:

# /etc/system
set forthdebug = 1

Setting forthdebug to be non-zero causes the misc/forthdebug module to be loaded and processed. It contains Forth code; it does not contain SPARC code. The most important step in processing the module is to read the module's contents into Solaris' heap and then have OBP have its Forth interpreter interpret the Forth code. This is done by Solaris passing the virtual address of the start of the Forth code to OBP via the Services API (see below).

---

To allow for symbolic access to Solaris addresses (from the OK prompt), one needs to load the obpsym module, which translates numeric addresses into symbolic addresses (on behalf of OBP). For the interested, this module leverages a couple of the Calls that are in the OBP API. A compliant OBP implementation implements a set of Services. Address translation is part of that Service interface.

The obpsym module can be loaded from the Solaris command line:

# modload -p misc/obpsym

Note that you want to reboot before you load the obpsym module. If you reboot after, you no longer have obpsym loaded.

---

The system is now almost prepared to debug at the OBP level. Use one of the above ways to get to the OK prompt, or use telnet to send a BREAK character from the console port:

# Ctrl-]
telnet> send break
ok

---

The last step is to execute this Forth command (eg, word)

ok kdbg-words

This enables OBP's Forth implementation to see the Forth code that was obtained from the misc/forthdebug file. One can run the following command to view the order in which OBP will lookup an entered command. The name of the left-most vocabulary has the highest priority:

ok order
context: kdbg-words forth forth options re-heads root     current: kdbg-words

Our next lesson will extend what we have learned here.

Oh... if you're wondering how to search for an OBP command/word, use this:

ok sifting thread

This will find "thread" as a sub-string in any word of any vocabulary... defined by the current vocabulary search order (eg, as shown by order).

Posted at 04:41PM Mar 03, 2008 by Andrew Rutz in obp-debug  |  Comments[1]