DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

udi_pio_probe(3udi)


Probe a PIO device that might not be present

SYNOPSIS

#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				0x20
 

ARGUMENTS 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.

STATUS VALUES UDI_OK

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.

REFERENCES udi_pio_trans


UDI Physical I/O Specification Contents