|
|
udi_pio_abort_sequence(3udi)
Register a PIO abort sequence
#include <udi.h>void udi_pio_abort_sequence ( udi_pio_handle_t pio_handle, udi_size_t scratch_requirement );ARGUMENTS pio_handle is a special PIO handle, previously acquired from udi_pio_map, whose associated trans list is designed to stop the associated device from initiating (mastering) transactions on its bus in case the driver fails.
scratch_requirement is the number of bytes of scratch space needed during processing of the associated trans list.
DESCRIPTION When a driver does something illegal, causes a system fault, or otherwise misbehaves, the UDI environment can "kill" the corresponding driver region. However, since the faulting driver region can no longer be trusted to execute correctly, the environment needs some way to stop the corresponding device from proceeding without having to re-execute the faulting region. udi_pio_abort_sequence provides the environment a PIO handle (with an associated trans_list) which it can use for this purpose.
The driver calls udi_pio_abort_sequence to register pio_handle with the environment. pio_handle must be mapped with a trans list that can be used to stop the corresponding device from initiating (mastering) transactions on the bus, including the generation of DMA transactions and interrupts. The PIO sequence specified by the associated trans list does not need to flush data or preserve device state, and should do the simplest sequence possible to stop the device, such as resetting it or otherwise stopping its ability to do bus mastering.
If needed, the registered trans list will be executed as if by udi_pio_trans. The UDI_PIO_SCRATCH addressing mode may be used to access up to scratch_requirement bytes of scratch space. UDI_PIO_BUF and UDI_PIO_MEM must not be used.
The abort trans list will be executed immediately in its own serialization domain without regard to the state of other PIO operations in other serialization domains; the abort operations will preempt any PIO trans lists currently executing or scheduled for executing and those PIO trans lists will be deallocated by the environment rather than being continued or executed. Additionally, no regions of this driver instance will be entered after initiation of the abort trans list and all channels to parents of that driver instance will be closed to release associated resources.
To facilitate handling faults in as wide a portion of the driver as possible, the driver should call udi_pio_abort_sequence as early as possible in its per-instance initialization sequence. If the device changes state in such a way that a different procedure is needed to shut it down, the driver may call udi_pio_abort_sequence again to replace the previously-registered sequence, but this should only be done if absolutely necessary.
The PIO handle passed to this service call is "given away" (as if with udi_pio_unmap). The driver must no longer access this handle.
A driver is not required to register a PIO abort sequence with this call if the operational characteristics of the device are such that it will not generate any activity (DMA, interrupts, etc) even if the driver is abruptly removed.