|
|
udi_pio_probe(3udi)
Probe a PIO device that might not be present
#include <udi.h>void udi_pio_probe ( udi_pio_probe_call_t *callback, udi_cb_t *gcb, udi_pio_handle_t pio_handle, void *mem_ptr, udi_ubit32_t pio_offset, udi_ubit8_t tran_size, udi_ubit8_t direction ); typedef void udi_pio_probe_call_t ( udi_cb_t *gcb, udi_status_t status ); /* Values for direction */#define UDI_PIO_IN 0x00 #define UDI_PIO_OUT 0x20ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Standard Calling Sequences" in the UDI Core Specification.
pio_handle is a PIO handle previously allocated via udi_pio_map.
mem_ptr is a pointer to a memory location which is the source or destination of the PIO transaction.
pio_offset is the offset into the mapped device at which to perform the transaction. There are no alignment requirements on pio_offset.
tran_size is the power-of-2 size of the PIO transaction. The actual size is 2tran_size bytes. The tran_size value must be from 0 to 5, corresponding to a transaction size of 1 to 32 bytes (256 bits). The mnemonic constants UDI_PIO_1BYTE through UDI_PIO_32BYTE are available for use in setting tran_size.
direction is exactly one of UDI_PIO_IN or UDI_PIO_OUT, to indicate the direction of transfer.
status indicates the success or failure of the PIO probe attempt.
DESCRIPTION This service call attempts to perform a PIO access to a device that may or may not be present. It will do this in such a way that there will be no adverse side effects (such as driver or system aborts) if there is in fact no device present. If a different device is present at the same or overlapping location then it might be accessed instead of the intended device, causing an indeterminate effect on the state of that device; environments are not required to prevent this from happening.
The trans list associated with pio_handle is ignored; instead, a single basic PIO transaction of 2tran_size bytes is performed, in the direction indicated by direction.
If a driver's device might not have been reliably enumerated and might not be actually present, udi_pio_probe must be used to determine if the device is present before using it for normal operation. Otherwise, udi_pio_probe should not be used. It is likely to be slower than udi_pio_trans, possibly affecting overall system performance as well. In some environments, use of udi_pio_probe may force the driver to be run only during certain stages of system initialization; such an environment may require system re-initialization in order to use a driver that uses udi_pio_probe.
In order for a driver to use udi_pio_probe, its region's "pio_probe" region attribute must be set to "yes". Some environments may refuse to use drivers with "pio_probe" set to "yes". See Section 1.4, "Extensions to Static Driver Properties" for details.
Transactions using udi_pio_probe are not guaranteed to be atomic.
If a driver determines that its device is not present during binding, it must log an error using udi_log_write and respond to the Management Agent with a status of UDI_STAT_NOT_RESPONDING via udi_channel_event_complete.
warnings Use of the mem_ptr parameter must conform to the rules described in "Using Memory Pointers with Asynchronous Service Calls" on page 5-2 of the UDI Core Specification.
UDI_STAT_HW_PROBLEM - the device failed to respond to the PIO access. Some environments may return "garbage" data in such cases, rather than indicating an error with UDI_STAT_HW_PROBLEM.