Configuring the Debug Agent

The debug agent is activated by enabling the DEBUG_SYSTEM feature with the configurator command as follows:

$ configurator -set DEBUG_SYSTEM=true 

The DEBUG_SYSTEM feature is set to true by default.

When the debug agent is activated, communications on the serial line are performed in binary mode (if the debug server is attached) or in ASCII mode (if it is not).

The debug agent has eight tunable options that you can configure with Ews or configurator. The following three tunables control the behavior of the debug agent when it is enabled (DEBUG_SYSTEM=true):

• dbg.agent.startup specifies the behavior of the debug agent at boot time. Possible values are stop or resume. In stop mode the system waits indefinitely until the debug server connects to the debug agent. In resume mode the system waits for no more than one second. In both cases, the debug agent issues the prompt:

  DebugAgent: trying to sync with DebugServer...

  over the serial line and sounds a beep. If the debug server does not connect, the system will continue booting and console operations will be performed without any processing by the debug agent, on the serial line.

• dbg.agent.exceptmode specifies the behavior of the debug agent when an exception (caught by deafult) is raised before the debug server has connected. Possible values are catch or forward. In catch mode the debug agent blocks the target until a debug server has connected and resumed the execution of the target. In forward mode the debug agent forwards all exceptions directly to the handlers installed by the microkernel.

• dbg.agent.consolemode specifies the operating mode of the system console. Possible values are sync or async. In sync mode the target is blocked until each message has been transmitted to the host for output and acknowledged. In async mode, console output is buffered and transmitted to the host periodically, either when the buffer is full or on each timer interrupt (whichever occurs first).

The following five tunables control the serial line used by the debug agent:

• dbg.agent.device specifies the serial device used by the debug agent. Possible values are COM1, COM2, COM3, or COM4. COM1 refers to communication port 1 on a PC, or the first serial line on other boards. COM2 refers to communication port 2 on a PC, or the second serial line on other boards, and so on.

• dbg.agent.baud specifies the baud rate of the serial line. Possible values are: 115200, 57600, 38400, 19200, 9600, 4800, 2400, or 1200.

• dbg.agent.parity specifies the parity of the serial line. Possible values are none, even, or odd.

• dbg.agent.databits specifies the number of data bits. The only possible value is 8.

• dbg.agent.stopbits specifies the number of stop bits. Possible values are 1 or 2.

When the debug agent is not active (DEBUG_SYSTEM=false), the serial line is used by the system debugging console, and the five tunables control the serial device and speed.