|
|
udi_pio_trans(3udi)
Generate PIO transactions
#include <udi.h>void udi_pio_trans ( udi_pio_trans_call_t *callback, udi_cb_t *gcb, udi_pio_handle_t pio_handle, udi_index_t start_label, udi_buf_t *buf, void *mem_ptr ); typedef void udi_pio_trans_call_t ( udi_cb_t *gcb, udi_buf_t *new_buf, udi_status_t status, udi_ubit16_t result );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 the PIO handle associated with the desired device register set and transaction list, previously acquired from udi_pio_map.
start_label specifies which UDI_PIO_LABEL value the trans list execution should begin at. A start_label value of zero indicates that the trans list execution should start from the beginning, otherwise values from 1-7 indicate a request to start the trans list at the corresponding UDI_PIO_LABEL position. Any other values for this argument are illegal.
buf is a pointer to a data buffer that can be accessed by the PIO transactions using UDI_PIO_BUF. If buf is set to NULL, UDI_PIO_BUF transactions are illegal for this call.
mem_ptr is a pointer to an auxiliary memory block that can be accessed by PIO transactions that specify UDI_PIO_MEM. If mem_ptr is set to NULL, such transactions are illegal for this call.
new_buf is a possibly new UDI buffer that the driver must use in place of the original buf after the callback is called, since the environment may need to re-allocate the buffer to accomodate new data added to the buffer as a result of this service call.
status is a UDI status code. If the PIO transactions all completed without error, it will be set to UDI_OK; otherwise it will be set to UDI_STAT_HW_PROBLEM. If not UDI_OK, the status code may already contain a correlate value.
result is a result code set by a UDI_PIO_END or a UDI_PIO_END_IMM transaction.
DESCRIPTION udi_pio_trans performs a series of one or more PIO transactions to the area of a device indicated by the PIO handle, pio_handle. The list of (possibly repeated) transactions to perform is given by the trans_list which was associated with the PIO handle at the time of udi_pio_map. See udi_pio_trans_t for a detailed description of PIO transactions.
Synchronization of udi_pio_trans calls and the execution of the corresponding transaction lists is provided by the environment independently from the region synchronization. For proper driver design refer to the PIO synchronization and ordering definitions on page 4-1.
If the PIO attributes associated with pio_handle indicate that the endianness of the device's data structures are different from the driver's endianness, udi_pio_trans will automatically perform necessary byte-swapping. The driver must not do the byte-swapping itself, as udi_pio_trans may be able to take advantage of special hardware support for byte-swapped PIO transactions.
Pacing delays and other attributes encoded in pio_handle, such as ordering and atomicity requirements, will be applied to each individual I/O operation.
Once the last transaction has been executed, including any pacing delay, the callback routine will be called. An implicit UDI_PIO_BARRIER will be executed at the end of the transaction list, but if UDI_PIO_SYNC or UDI_PIO_SYNC_OUT are required they must be explicitly included.
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 A UDI status code indicating the success or failure of the PIO transactions. If a hardware error, such as a bus timeout or parity error, is detected in conjunction with a PIO transaction, execution of the PIO transaction list is terminated and status is set to UDI_STAT_HW_PROBLEM. Transactions following the one that caused the error may or may not be executed. Environments are not required to detect errors during udi_pio_trans; in such environments, the effect of a PIO hardware error is indeterminate and may include driver or system termination. If a driver expects that the PIO might reasonably fail (e.g. because the device is not present) it must use udi_pio_probe instead of udi_pio_trans.