isaFi(9DDI)

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO

NAME

isaFi- ISA Fault Injection Driver Interface

SYNOPSIS

#include <ddi/isa/isaFi.h>

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

DDI

DESCRIPTION

Provides ISA fault injection driver services.

EXTENDED DESCRIPTION

The purpose of a fault injection bus driver is to verify that a device driver is resilient to hardware faults. It helps build and validate hardened device drivers. A fault injection bus driver is a filter between a real bus driver and its connected device drivers. The existence of such a filter is totally transparent to both the bus and the device drivers. From a bus driver perspective, the fault injection bus driver looks like a normal instance of a device driver started on a child device node. From a device driver perspective, the fault injection bus driver looks like a normal parent bus driver providing the requested ISA DDI. Thus, an ISA fault injection bus driver usually provides two interfaces:

1. The standard ISA DDI is provided to the device driver being tested. These operations are implemented as wrapper functions which call appropriate methods on the real parent bus driver (upstream) and call appropriate handlers in the device driver (downstream).

2. The ISA fault injection DDI allows a fault-injector client to change this basic behavior by injecting faults to simulate a device malfunction.

By monitoring the device driver requests issued to the ISA bus, a fault injection bus driver is able to perform multiple checks on the validity of those requests and their arguments. This allows you to detect many problems in the device drivers. Typically, a fault injection bus driver is able to check whether:

• An ISA bus resource is correctly allocated before being used.

• An ISA bus resource is not used twice.

• The arguments to an ISA DDI call are in the correct range.

• All ISA bus resources are freed when the driver closes its connection to the bus.

The ISA bus fault injection DDI provides all services defined by the common bus fault injection DDI, plus some ISA-specific services:

• Notifying the device driver that it has connected to the ISA bus.

• Restarting a failed device driver.

• Controlling interrupt delivery to a device driver:

  • Delivering a spurious interrupt.

  • Ignoring a device interrupt.

• Controlling I/O register access from a device driver:

  • Corrupting I/O register load/store operations.

  • Ignoring an I/O store operation.

  • Raising an I/O error.

• Controlling (32-bit address) device memory access from a device driver:

  • Corrupting content of a memory location.

  • Raising a memory access error.

• Raising bus events to a device driver.

• Refusing allocation of a ISA bus resource to a device driver.

• Chaining required fault injection operations into an ordered sequential set.

• Managing the chained set of fault injection operations:

  • Starting a set of operations.

  • Stopping a running set of operations.

Service Routines

The ISA fault injection service routines are defined by the IsaFiOps structure. A pointer to the IsaFiOps structure is exported by a ISA fault injection driver via the svDeviceRegister() microkernel call. A fault injector client invokes the svDeviceLookup() and svDeviceEntry() microkernel calls in order to obtain a pointer to the fault injection service routine vector. Once the pointer is obtained, the driver client is able to invoke the driver service routines (via indirect function calls).

The IsaFiOps structure is the following:

     typedef struct IsaFiOps {

      IsaFiVersion version;

      KnError
      (*open) (IsaFiId         busId,
               IsaFiCallbacks* cb,
               void*           cookie);

      void
      (*close) (IsaFiId busId);

      KnError
      (*restart) (IsaFiId busId);

      KnError
      (*intr_get_access) (IsaFiId        busId,
                          IsaPropIntr*   intr,
                          IsaFiIntrOps** intrOps,
		          IsaFiIntrId*   intrId);
      void
      (*intr_release) (IsaFiIntrId intrId);

      KnError
      (*io_get_access) (IsaFiId        busId,
                        IsaPropIoRegs* ioRegs,
                        IsaFiIoOps**   ioOps,
                        IsaFiIoId*     ioId);
      void
      (*io_release) (IsaFiIoId ioId);

      KnError
      (*mem_get_access) (IsaFiId        busId,
                         IsaPropMemRgn* memRgn,
                         IsaFiMemOps**  memOps,
                         IsaFiMemId*    memId);
      KnError
      (*mem_release) (IsaFiMemId memId);

      KnError
      (*dma_get_access) (IsaFiId	budId,
                         IsaPropDma	dmaProp,
                         IsaFiDmaOps**	dmaOps,
                         IsaFiDmaId	dmaId);

      KnError
      (*dma_release) (IsaFiDmaId dmaId); 

      KnError
      (*bus_evt_raise) (IsaFiId      busId,
                        IsaBusEvent  event,
                        void*        arg,
                        IsaFiOpDesc* opDesc,
                        IsaFiOpId*   opId);

      KnError
      (*resource_refuse) (IsaFiId      busId,
                          char*        propName,
                          IsaFiOpDesc* opDesc,
                          IsaFiOpId*   opId);

      KnError
      (*op_chain) (IsaFiId   busId,
                   IsaFiOpId opId,
                   IsaFiOpId nextOp);

      KnError
      (*op_start) (IsaFiId          busId,
                   IsaFiOpId        opId,
                   IsaFiExecHandler execHandler,
                   void*            cookie,
                   IsaFiRunId*      runId);

      void
      (*op_stop) (IsaFiRunId runId);

      KnError
      (*op_free) (IsaFiOpId opId);

      KnError
      (*chain_free) (IsaFiOpId opId);

     } IsaFiOps;

The version field specifies the version number of the ISA fault injection API. The version number is increased by increments each time one of the DDI structures is extended to include new service routines.

open()/close>()

open() must be the first call issued by the client to the fault injection bus driver. It establishes a connection between the fault injection bus driver and its client. The busId argument specifies the ISA fault injection bus driver instance. The conf argument specifies the limits to use when computing random delays for fault injection operations. It points to a IsaFiConf structure which it inherits from the BusFiConf structure:

     typedef struct BusFiConf {
         unsigned int minCount;     /* lower limit for random count */
         unsigned int maxCount;     /* upper limit for random count */
         KnTimeVal minTimeVal;      /* lower limit for random timeval */
         KnTimeVal maxTimeVal;      /* upper limit for random timeval */
     } BusFiConf;

The cb argument specifies the fault injector client notification handlers. It points to a IsaFiCallbacks structure which it inherits from the BusFiCallbacks structure:

     typedef struct BusFiCallbacks {
         void (*openNotify) (void* cookie);
         void (*closeNotify) (void* cookie);
     } BusFiCallbacks;

The openNotify handler notifies the client that the driver being tested has just called its bus driver's open() function (initialization).

The closeNotify handler notifies the client that the driver being tested has just called its bus driver's close() function (shutdown).

The cookie argument specifies a client's cookie. This is an opaque parameter for the fault injection bus driver which is passed back as an argument when calling the client's notification handlers.

Upon successful completion, open returns K_OK. Otherwise, one of the following error codes is returned:

K_EINVAL

The conf argument is invalid.

K_EBUSY

The fault injection bus driver identified by busId is already in use (opened).

K_ENOMEM

The system is out of memory.

The close() routine releases the client/fault injection bus driver connection. It must be the last call issued.

restart()

restart() tries to restart the child driver tested which is bound to the device node. It calls the drv_init() method of the driver. This operation is typically used by the fault injector client to restart a failed device driver.

Upon successful completion, restart returns K_OK. Otherwise, an error code is returned as described below:

K_EBUSY

The child driver is already started.

K_EFAIL

No child driver is bound to the device node, or it failed to initialize.

ISA bus resource properties

Fault injection and control over the driver operations tested are requested for each ISA bus resource. The ISA bus resources used by a device are specified as properties attached to the device node. The properties used for isaFi DDI are those defined by the ISA DDI. Refer to isa(9DDI) for more details about ISA bus properties.

Fault injection operation attributes

When a fault injection bus driver is requested to simulate a fault on a given bus resource used by a device driver, it creates a fault injection operation. The fault injector client can specify attributes for each operation created by passing a IsaFiOpDesc structure to the driver. The IsaFiOpDesc inherits from the BusFiOpDesc structure, described below:

     typedef uint32_f BusFiOpAttr;

     typedef struct BusFiOpDesc {
         BusFiOpAttr attr;
         uint32_f count;
         KnTimeVal timeval;
     } BusFiOpDesc;

attr is a bit field that should be built by oring the following constant values:

ISAFI_OP_COUNT

The count field is valid and indicates the number of events to wait for before executing the operation.

ISAFI_OP_TIMEVAL

The timeval field is valid and indicates the delay (specified as a KnTimeVal structure) to wait for before executing the operation.

ISAFI_OP_RANDOM

The fault injection bus driver will choose a random delay value (count or timeval) before executing the operation.

ISAFI_OP_SYSLOG

The fault injection bus driver will log a message into the system when executing the operation.

intr_get_access()/intr_release()

The intr_get_access() service routine obtains access and control over the source handling of a given bus interrupt. The busId argument specifies the fault injection bus driver instance (taken from svDeviceEntry()). The intr argument specifies the ISA interrupt source. It points to a IsaPropIntr interrupt property value.

Typically, a fault injector client should find such a property (attached to the device node) using the "intr" name, obtain a pointer to the property value and specify it in intr_get_access().

Upon successful completion, intr_get_access() returns K_OK, and a valid intrOps/intrId pair.

intrOps points to a IsaFiIntrOps structure which provides the fault injection service routines specific to the interrupt source requested (see IsaFiIntrOps).

intrId is opaque for the fault injector client. It is passed back to the fault injection bus driver as an argument in subsequent invocations of the IsaFiIntrOps and intr_release() service routines.

In case of failure, one of the following error codes is returned:

K_EINVAL

The specified interrupt property is invalid.

K_ENOMEM

The system is out of memory.

The intr_release() service routine releases access to the interrupt source.

Fault injection on interrupts

IsaFiIntrOps provides the fault injection services defined for ISA interrupt sources and inherits from the BusFiIntrOps:

     typedef struct BusFiIntrOps {
         KnError
         (*intr_ignore) (BusFiIntrId intrId,
                         BusIntrStatus status,
                         BusFiOpDesc* opDesc,
                         BusFiOpId* opId);
         KnError
         (*intr_trigger) (BusFiIntrId intrId,
                          BusFiOpDesc* opDesc,
                          BusFiOpId* opId);
     } BusFiIntrOps;

The intr_ignore() service routine creates a fault injection operation to prevent delivery of a given interrupt to the driver being tested. The intrId specifies the interrupt source. The status argument specifies the interrupt status to return to the real bus driver in place of the value that would have been returned by the interrupt handler, if called. The status must be in:

ISA_INTR_CLAIMED

The interrupt handler of the device driver tested will not be called, but the interrupt will be considered to be claimed (handled) by the underlying bus driver.

ISA_INTR_UNCLAIMED

The interrupt handler of the device driver tested will not be called, and the interrupt will be considered to be unclaimed (not handled) by the underlying bus driver. This may be useful to simulate interrupts on an interrupt line which are "stuck".

The opDesc argument specifies the required attributes for the operation created (see the fault injection operations attributes).

Upon successful completion, intr_ignore returns K_OK, and a valid operation identifier in the opId argument. Otherwise, the following error code is returned:

K_ENOMEM

The system is out of memory.

The intr_trigger() service routine creates a fault injection operation to simulate the occurrence of a given interrupt and to trigger attached interrupt handlers in the device driver being tested. The intrId argument specifies the interrupt source. The opDescargument specifies the required attributes for the operation created (see the fault injection operation attributes).

Upon successful completion, intr_trigger() returns K_OK, and a valid operation identifier in the opId argument. Otherwise, the following error code is returned:

K_ENOMEM

The system is out of memory.

io_get_access()/io_release()

The io_get_access() service routine gets access and control over the load and store operations performed by the tested driver on a given ISA I/O register range. The busId argument specifies the fault injection bus driver instance (taken from svDeviceEntry()). The ioRegs argument specifies the range of the ISA I/O register and points to IsaPropIoRegs.

Typically, a fault injector client should find such properties (attached to the device node) using the "io-regs" name, obtain a pointer to the property value and specify it in io_get_access().

Upon successful completion, io_get_access() returns K_OK, and a valid ioOps/ioId pair.

ioOps points to a IsaFiIoOps structure which provides the fault injection service routines specific to the range of the requested I/O register (see IsaFiIoOps).

ioId is opaque for the fault injector client. It is passed back to the fault injection bus driver as an argument in subsequent invocations of the IsaFiIoOps and io_release() service routines.

In case of failure, one of the following error codes is returned:

K_EINVAL

The specified I/O register range property is invalid.

K_ENOMEM

The system is out of memory.

The io_release() service routine releases access to the I/O register range.

Fault injection on ISA I/O register ranges

The IsaFiIoOps provides the fault injection services defined for ISA I/O register ranges:

     typedef struct IsaFiIoOps {
      KnError
      (*load_8) (IsaFiIoId    ioId,
                 IsaSize      offset,
                 IsaFiMask_8* mask,
                 IsaFiOpDesc* opDesc,
                 IsaFiOpId*   opId);
      KnError
      (*load_16) (IsaFiIoId     ioId,
                  IsaSize       offset,
                  IsaFiMask_16* mask,
                  IsaFiOpDesc*  opDesc,
                  IsaFiOpId*    opId);
      KnError
      (*load_32) (IsaFiIoId     ioId,
                  IsaSize       offset,
                  IsaFiMask_32* mask,
                  IsaFiOpDesc*  opDesc,
                  IsaFiOpId*    opId);
      KnError
      (*load_64) (IsaFiIoId     ioId,
                  IsaSize       offset,
                  IsaFiMask_64* mask,
                  IsaFiOpDesc*  opDesc,
                  IsaFiOpId*    opId);
      KnError
      (*store_8) (IsaFiIoId     ioId,
                  IsaSize       offset,
                  IsaFiMask_8*  mask,
                  IsaFiOpDesc*  opDesc,
                  IsaFiOpId*    opId);
      KnError
      (*store_16) (IsaFiIoId     ioId,
                   IsaSize       offset,
                   IsaFiMask_16* mask,
                   IsaFiOpDesc*  opDesc,
                   IsaFiOpId*    opId);
      KnError
      (*store_32) (IsaFiIoId     ioId,
                   IsaSize       offset,
                   IsaFiMask_32* mask,
                   IsaFiOpDesc*  opDesc,
                   IsaFiOpId*    opId);
      KnError
      (*store_64) (IsaFiIoId     ioId,
                   IsaSize       offset,
                   IsaFiMask_64* mask,
                   IsaFiOpDesc*  opDesc,
                   IsaFiOpId*    opId);
      KnError
      (*store_ignore) (IsaFiIoId     ioId,
                       IsaSize       offset,
                       IsaFiOpDesc*  opDesc,
                       IsaFiOpId*    opId);
      KnError
      (*error_raise) (IsaFiIoId    ioId,
                      IsaBusError* error,
                      IsaFiOpDesc* opDesc,
                      IsaFiOpId*   opId);
     } IsaFiIoOps;

The load_xx() set of service routines create a fault injection operation to corrupt (modify) the value read from a given I/O register by the device driver being tested. The value read from the register is modified using bit mask values before being returned to the caller. The ioId argument specifies the I/O register range. The offset argument specifies the offset of the register within the I/O range to be corrupted. offset must be in the mapped I/O range, or can be set to ISAFI_OFFSET_ALL to specify any valid offset in the I/O range. The mask argument points to a IsaFiMask_xx structure which provides clear and set bitmasks. These bitmasks are used in the following formula to corrupt the loaded value:

     returned_value = (loaded_value & clear) | set;

Alternatively, the mask argument may be set to NULL to specify that the fault injection bus driver must choose random clear and set bitmasks to corrupt the value read from the I/O register. The opDesc argument specifies the required attributes for the operation created (see the fault injection operation attributes).

Upon successful completion, the load_xx() set of routines returns K_OK, and a valid operation identifier in the opId argument. Otherwise, one of the following error codes is returned:

K_EINVAL

offset is out of the I/O register range.

K_ENOMEM

The system is out of memory.

The store_xx() set of service routines creates a fault injection operation to corrupt (modify) the value stored in a given I/O register by the device driver being tested. The value from the caller is modified using bitmask values before being stored in the I/O register. The ioId argument specifies the I/O register range. The offset argument specifies the offset of the register within the I/O range to be corrupted. offset must be in the mapped I/O range, or can be set to ISAFI_OFFSET_ALL to specify any valid offset in the I/O range. The mask argument points to a IsaFiMask_xx() structure which provides clear and set bitmasks. These bitmasks are used in the following formula to corrupt the loaded value:

     stored_value = (provided_value & clear) | set;

Alternatively, the mask argument may be set to NULL to specify that the fault injection bus driver must choose random clear and set bitmasks to corrupt the value stored in the I/O register. The opDesc argument specifies the required attributes for the created operation (see the fault injection operation attributes).

Upon successful completion, the store_xx() set of routines returns K_OK, and a valid operation identifier in the opId argument. Otherwise, one of the following error codes is returned:

K_EINVAL

offset is out of the I/O register range.

K_ENOMEM

The system is out of memory.

The store_ignore() service routine creates a fault injection operation to ignore an I/O store operation requested for a given I/O register by the device driver being tested. The store operation is silently discarded. The ioId argument specifies the I/O register range. The offset argument specifies the offset of the register within the I/O range for which an I/O store should be ignored. offset must be in the mapped I/O range or can be set to ISAFI_OFFSET_ALL to specify any valid offset in the I/O range. The opDesc argument specifies the required attributes for the created operation (see the fault injection operation attributes).

Upon successful completion, the store_ignore() routine returns K_OK, and a valid operation identifier in the opId argument.

Otherwise, one of the following error codes is returned:

K_EINVAL

offset is out of the I/O register range.

K_ENOMEM

The system is out of memory.

The error_raise() service routine creates a fault injection operation to simulate and raise the given I/O error to the device driver tested. The ioId argument specifies the I/O register range. The error argument specifies the error to be raised. It points to a IsaError structure indicating the error code and the offset within the I/O range where the error occurred. Refer to isa(9DDI) for the definition of IsaError. The opDesc argument specifies the required attributes for the created operation (see the fault injection operation attributes).

Upon successful completion, the error_raise() routine returns K_OK, and a valid operation identifier in the opId argument.

Otherwise, one of the following error codes is returned:

K_EINVAL

The error argument is invalid.

K_ENOMEM

The system is out of memory.

mem_get_access()/mem_ release()

The mem_get_access() service routine gets access and control over a given bus memory region used by the driver tested. The busId argument specifies the fault injection bus driver instance (taken from svDeviceEntry()). The memRgn argument specifies the ISA bus memory region. It points to a IsaPropMemRgn property value.

Typically, a fault injector client should find such a property (attached to the device node) using the "mem-rgn name", obtain a pointer to the property value and specify it in mem_get_access().

Upon successful completion, mem_get_access() returns K_OK, and a valid memOps/memId pair.

memOps points to a IsaFiMemOps structure which provides the fault injection service routines specific to the requested ISA memory region (see IsaFiMemOps).

memId is opaque for the fault injector client. It is passed back to the fault injection bus driver as an argument in subsequent invocations of the IsaFiMemOps and mem_release() service routines.

In case of failure, an error code is returned as described below:

K_EINVAL

The specified memory region property is invalid.

K_ENOMEM

The system is out of memory.

The mem_release() service routine releases access to the memory region.

Fault injection on ISA memory region

IsaFiMemOps provides the fault injection services defined for ISA memory regions:

     typedef struct IsaFiMemOps {
        KnError
        (*corrupt) (IsaFiMemId   memId,
                    IsaSize      offset,
                    IsaFiMask_8* mask,
                    IsaFiOpDesc* opDesc,
                    IsaFiOpId*   opId);
        KnError
        (*error_raise) (IsaFiMemId   memId,
                        IsaBusError* error,
                        IsaFiOpDesc* opDesc,
                        IsaFiOpId*   opId);
     } IsaFiMemOps;

The corrupt() routine creates a fault injection operation to corrupt (modify) a given byte in a ISA memory region which is used by the driver being tested. The memory byte is read and modified using bit mask values before being written back to ISA memory. The memId argument specifies the memory region. The offset argument specifies the offset of the byte that should be corrupted within the memory region. offset must be in the range of the mapped ISA memory region, or it can be set to ISAFI_OFFSET_ALL to specify any valid offset in the memory region. The mask argument points to a IsaFiMask_8 structure which provides clear and set bitmasks. These bitmasks are used in the following formula to corrupt the loaded value:

     corrupted_value = (initial_value & clear) | set;

Alternatively, the mask argument may be set to NULL to specify that the fault injection bus driver must choose random clear and set bitmasks to corrupt the memory region location. The opDesc argument specifies the required attributes for the operation created (see the fault injection operation attributes).

Upon successful completion, the corrupt() routine returns K_OK, and a valid operation identifier in the opId argument.

Otherwise, one of the following error codes is returned:

K_EINVAL

offset is outside the memory region, or the ISAFI_OP_COUNT attribute is set in opDesc.

K_ENOMEM

The system is out of memory.

The error_raise() service routine creates a fault injection operation to simulate and raise the given error to the device driver tested. The memId argument specifies the memory region. The error argument specifies the ISA error to be raised. It points to a IsaError structure indicating the error code and the offset within the memory region where the error occurred. Refer to isa(9DDI) for the definition of IsaError. The opDesc argument specifies the required attributes for the operation created (see the fault injection operation attributes).

Upon successful completion, the error_raise routine returns K_OK, and a valid operation identifier in the opId argument.

Otherwise, one of the following error codes is returned:

K_EINVAL

The error argument is invalid, or the ISAFI_OP_COUNT attribute is set in opDesc.

K_ENOMEM

The system is out of memory.

dma_get_access()/dma_release()

The dma_get_access() service routine gets access and control over a given bus memory region used by the driver tested. The busId argument specifies the fault injection bus driver instance (taken from svDeviceEntry()). The dmaProp> argument specifies the amount of memory to transfer and dma channel to use. It points to a IsaPropDma property value.

Typically, a fault injector client should find such a property (attached to the device node) using the dma name, obtain a pointer to the property value and specify it in dma_get_access().

Upon successful completion, dma_get_access() returns K_OK, and a valid dmaOps/dmaId pair.

dmaOps points to a IsaFiDmaOps structure which provides the fault injection service routines specific to the requested ISA dma transfer (see IsaFiDmaOps).

dmaId is opaque for the fault injector client. It is passed back to the fault injection bus driver as an argument in subsequent invocations of the IsaFiDmaOps and dma_release() service routines.

In case of failure, an error code is returned as described below:

K_EINVAL

The specified dma property is invalid.

K_ENOMEM

The system is out of memory.

The dma_release() service routine releases access to the dma channel.

---

Note -

These operations are not implememented in isaFi driver because of a lack of definition of the dma_mem() operations (dma_mem_get_access(), dma_mem_release()).

---

Fault injection on ISA dma transfer

IsaFiDmaOps provides the fault injection services defined for ISA dma channel:

     typedef struct IsaFiDmaOps {
        KnError
        (*dma_refuse) (IsaFiDmaId   memId,
                       IsaFiOpId*   opId);
     } IsaFiDmaOps;

The dma_refuse() routine creates a fault injection operation to refuse the requested dma channel which is requested by the tested driver. The dmaId argument specifies the channel.

Upon successful completion, the corrupt routine returns K_OK, and a valid operation identifier in the opId argument.

Otherwise, one of the following error codes is returned:

K_ENOMEM

The system is out of memory.

dma_mem_get_access()/dma_mem_release()

These operations are not implemented because no properties are attached to the node that describe the memory region the tested driver allocate. These regions are dynamicaly allocated and the isaFi driver have no way of knowing about these.

bus_evt_raise()

The bus_evt_raise() service routine creates a fault injection operation to simulate and raise the given ISA bus event to the device driver tested. The busId argument specifies the fault injection bus driver instance (taken from svDeviceEntry()). The event and arg arguments specify the ISA event to be raised. Refer to isa(9DDI) for details about available ISA event values and the associated specific arguments. The opDesc argument specifies the required attributes for the operation created (see the fault injection operation attributes).

Upon successful completion, the bus_evt_raise() routine returns K_OK, and a valid operation identifier in the opId argument. Otherwise, one of the following error codes is returned:

K_EINVAL

The event argument is invalid, or the ISAFI_OP_COUNT attribute is set in opDesc.

K_ENOMEM

The system is out of memory.

op_chain()/op_free()/chain_free()

The op_chain() service routine links together previously created fault injection operations in order to obtain a set of operations that will be executed sequentially. op_chain() is the elementary operation allowing you to link two fault injection operations together, however it can be used repeatedly to create sets of any length. In addition, a cyclic set can be built by chaining the first and the last operations in the set. The busId argument specifies the fault injection bus driver instance (taken from svDeviceEntry()). The opId and nextOp arguments specify the fault injection operations to be chained. opId must be a stand-alone operation, that is, it should not be chained. The operations are chained in such a way that opId will always execute before nextOp in the set.

Upon successful completion, the op_chain() routine returns K_OK. Otherwise, one of the following error codes is returned:

K_EINVAL

The opId argument is already chained to another operation, or opId and nextOp are already chained into different sets.

K_EBUSY

opId or nextOp are already chained into a set of operations which is already running.

K_ENOMEM

The system is out of memory.

The op_free() service routine frees a previously-created fault injection operation. The operation is unlinked from its set of operations. The opId argument specifies the fault injection operation to be freed. It must not be chained into a set of operations which is already running.

Upon successful completion, op_free() routine returns K_OK.

Otherwise, the following error code is returned:

K_EBUSY

opId is chained into a set of operations which is already running.

The chain_free() service routine frees a previously created fault injection operation and all the operations chained in the same set. The opId argument specifies which one of the fault injection operation in the set is to be freed. The set of operations must not be running.

Upon successful completion, the chain_free() routine returns K_OK. Otherwise, the following error code is returned:

K_EBUSY

opId is chained into a set of operations which is already running.

op_start()/op_stop()

The op_start() service routine starts executing a previously created fault injection operation (or set of operations).

The busId argument specifies the fault injection bus driver instance (taken from svDeviceEntry()). The opId argument specifies the fault injection operation to be started. If opId is chained in a set of operations, execution will begin with the first operation in the set (which may be different from opId). The execHandler argument is a handler in the client that is called back to report status or events related to the execution of the operation (or set of operations).

The execHandler may be called back in the context of an interrupt. Therefore the API used in such a handler is restricted to an interrupt handler.

The ISA fault injection execution handler inherits from the common bus execution handler:

     
     typedef void (*BusFiExecHandler) (void*       cookie,
                                       BusFiRunId  runId,
                                       BusFiOpId   opId,
                                       BusFiReason reason);

The cookie argument is opaque for the fault injection bus driver and is passed back as the first argument to the execHandler handler when called. The second argument of the execHandler handler is the identifier of the operation, or set of operations, running. The third argument is the identifier of the operation in the set to which the status/event applies. The last argument gives the reason for the call and indicates the execution status, as follows:

ISAFI_EXEC_DONE

The last operation in a set has been executed and it has no chained operations. The set is considered to be terminated and is put in the stopped state. opId specifies the last operation to be executed.

ISAFI_EXEC_LOOPED

The last operation in a cyclic set has been executed and the fault injection driver has looped back to the first operation. The set of operations is still running and opId specifies the last operation to be executed.

ISAFI_EXEC_STOPPED

The set of operations has been stopped by the fault injector client using the op_stop service routine. opId specifies the last operation to be executed.

ISAFI_EXEC_FREED

The tested driver has released a ISA bus resource (*_unmap, *_detach) which was used to inject faults. The associated set of operations is stopped and opId specifies the operation associated to the freed resource.

ISAFI_EXEC_CLOSED

The driver tested has closed its connection to the bus driver. The remaining set of operations, relating to resources which have not yet been released, is stopped. The opId specifies the last operation to be executed.

Upon successful completion, the op_start() routine returns K_OK and an identifier for the operation, or set of operations, running is returned into runId (an argument to be passed to the op_stop() routine). Otherwise, one of the following error codes is returned:

K_EBUSY

The operation identified by opId has already started or is chained into a set of operations which are already running.

K_ENOMEM

The system is out of memory.

The op_stop() service routine stops a previously-started fault injection operation or set of operations. The runId argument must be an identifier returned by a previous call to the op_start() routine.

Allowed Calling Contexts

The following table specifies the contexts in which a caller is allowed to invoke each service:

Services	Base level	DKI thread	Interrupt	Blocking
IsaFiOps.open	-	+	-	+
IsaFiOps.close	-	+	-	+
IsaFiOps.restart	-	+	-	+
IsaFiOps.intr_get_acces	-	+	-	+
IsaFiOps.intr_release	-	+	-	+
IsaFiOps.io_get_access	-	+	-	+
IsaFiOps.io_release	-	+	-	+
IsaFiOps.mem_get_acces	-	+	-	+
IsaFiOps.mem_release	-	+	-	+
IsaFiOps.dma_get_access	-	+	-	+
IsaFiOps.dma_release	-	+	-	+
IsaFiOps.bus_evt_raise	-	+	-	+
IsaFiOps.resource_refuse	-	+	-	+
IsaFiOps.op_chain	-	+	-	+
IsaFiOps.op_start	-	+	-	+
IsaFiOps.op_stop	-	+	-	+
IsaFiOps.op_free	-	+	-	+
IsaFiOps.chain_free	-	+	-	+
IsaFiIntrOps.intr_ignore	-	+	-	+
IsaFiIntrOps.intr_trigger	-	+	-	+
IsaFiConfOps.load_xx	-	+	-	+
IsaFiConfOps.store_xx	-	+	-	+
IsaFiConfOps.store_ignore	-	+	-	+
IsaFiIofOps.load_xx	-	+	-	+
IsaFiIoOps.store_xx	-	+	-	+
IsaFiIoOps.store_ignore	-	+	-	+
IsaFiIoOps.error_raise	-	+	-	+
IsaFiDmaOps.refuse (see note)	-	+	-	+
IsaFiDmaOps.corrupt (see note)	-	+	-	+
IsaFiDmaOps.error_raise (see note)	-	+	-	+
IsaFiMemOps.corrupt	-	+	-	+
IsaMemOps.error_raise	-	+	-	+

---

Note -

These operations are not implemented and actually do nothing

---

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

SEE ALSO

bus(9DDI), busFi(9DDI), svDeviceRegister(9DKI), svDeviceLookup(9DKI), svDeviceEntry(9DKI), dtreePropFind(9DKI), dtreePropValue(9DKI), svMemAlloc(9DKI), svDkiThreadCall(9DKI)

ChorusOS 5.0  Last Revised December 2001

NAME | SYNOPSIS | API RESTRICTIONS | FEATURES | DESCRIPTION | EXTENDED DESCRIPTION | ATTRIBUTES | SEE ALSO