Testing the Driver

This section describes how to create and inject faults by using the th_define(1M) and th_manage(1M) commands.

Creating Faults

The th_define utility provides an interface to the bofi device driver for defining errdefs. An errdef corresponds to a specification for how to corrupt a device driver's accesses to its hardware. The th_define command-line arguments determine the precise nature of the fault to be injected. If the supplied arguments define a consistent errdef, the th_define process stores the errdef with the bofi driver. The process suspends itself until the criteria given by the errdef becomes satisfied. In practice, the suspension ends when the access counts go to zero (0).

Injecting Faults

The test harness operates at the level of data accesses. A data access has the following characteristics:

• Type of hardware being accessed (driver name)

• Instance of the hardware being accessed (driver instance)

• Register set being tested

• Subset of the register set that is targeted

• Direction of the transfer (read or write)

• Type of access (PIO or DMA)

The test harness intercepts data accesses and injects appropriate faults into the driver. An errdef, specified by the th_define(1M) command, encodes the following information:

• The driver instance and register set being tested (-n name, -i instance, and -r reg_number).

• The subset of the register set eligible for corruption. This subset is indicated by providing an offset into the register set and a length from that offset (-l offset [len]).

• The kind of access to be intercepted: log, pio, dma, pio_r, pio_w, dma_r, dma_w, intr (-a acc_types).

• How many accesses should be faulted (-c count [failcount]).

• The kind of corruption that should be applied to a qualifying access (-o operator [operand]).

  • Replace datum with a fixed value (EQUAL)

  • Perform a bitwise operation on the datum (AND, OR, XOR)

  • Ignore the transfer (for host to I/O accesses NO_TRANSFER)

  • Lose, delay, or inject spurious interrupts (LOSE, DELAY, EXTRA)

Use the -a acc_chk option to simulate framework faults in an errdef.

Fault-Injection Process

The process of injecting a fault involves two phases:

1. Use the th_define(1M) command to create errdefs.

   Create errdefs by passing test definitions to the bofi driver, which stores the definitions so they can be accessed by using the th_manage(1M) command.

2. Create a workload, then use the th_manage command to activate and manage the errdef.

   The th_manage command is a user interface to the various ioctls that are recognized by the bofi harness driver. The th_manage command operates at the level of driver names and instances and includes these commands: get_handles to list access handles, start to activate errdefs, and stop to deactivate errdefs.

   The activation of an errdef results in qualifying data accesses to be faulted. The th_manage utility supports these commands: broadcast to provide the current state of the errdef and clear_errors to clear the errdef.

   See the th_define(1M) and th_manage(1M) man pages for more information.

Test Harness Warnings

You can configure the test harness to handle warning messages in the following ways:

• Write warning messages to the console

• Write warning messages to the console and then panic the system

Use the second method to help pinpoint the root cause of a problem.

When the bofi-range-check property value is set to warn, the harness prints the following messages (or panics if set to panic) when it detects a range violation of a DDI function by your driver:

ddi_getX() out of range addr %x not in %x
ddi_putX() out of range addr %x not in %x
ddi_rep_getX() out of range addr %x not in %x
ddi_rep_putX() out of range addr %x not in %x

X is 8, 16, 32, or 64.

When the harness has been requested to insert over 1000 extra interrupts, the following message is printed if the driver does not detect interrupt jabber:

undetected interrupt jabber - %s %d