[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Understanding the Diagnostic Subsystem for AIX

pdiag_dd_read

Purpose

The pdiag_dd_read() function performs a read operation on a resource.

Syntax


#include <sys/pdiagex_dds.h>
int32 pdiag_dd_read ( handle, type, offset, data, flags )
pdiag_info_handle_t  handle; 
uint32  type;
uint32  offset;
pdiag_addr_t  data;
pdiag_opflags_t  *flags;

Description

The pdiag_dd_read() function reads the data from the specified address. If the user enables the times variable, timing information for this function is also returned. Each read performed is dependent on the memio operation and count parameters.

PDIAG_IO_OP If count is 1, data is read from the specified bus I/O offset address.
PDIAG_MEM_OP If count is 1, data is read from the specified memory offset address.
PDIAG_POS_OP If count is 1, data is read from the specified POS offset address.

A specified number of read accesses from the offset address may be performed if count is greater than 1. The user may choose to read the data from one location (the offset address) count times, or read the data from count consecutive locations, starting at the offset address. In either case, the read data is stored in the data buffer starting at the specified buffer address.

Note: When reading data, it is imperative that the read data buffer is at least the size of count * type (unless the read data buffer address is not being incremented). If this is not done, meaningless data is written to an area outside the read buffer. This may cause problems with your testing.

Execution Environment

The pdiag_dd_read() function can be called from the process or the interrupt environment.

Parameters

handle Points to pdiag_info_handle_t structure which is returned from pdiag_open().
type Defines the data length (byte, word or long) read from the address specified when type is IOCHAR8, IOSHORT16, and IOLONG32 respectively.
offset Offset value that is dependent on the type of operation being performed. It can be one of the following values:
PDIAG_IO_OP offset from base I/O address.
PDIAG_MEM_OP offset from base memory address.
PDIAG_POS_OP offset from base POS address.
data Address of the information read from the specified address.
Note: For PDIAG_IO_OP and PDIAG_MEM_OP: The value read from the specified offset will be placed at the specified data address in the form specified by type. If the data buffer is smaller than the specified type, the value will overwrite the bounds of your buffer. If the data buffer is larger than the specified type, the value will reside in the upper type bytes of the buffer.

For PDIAG_POS_OP: The value read from the specified offset will be placed at the specified data address and will occupy 1 byte. If the data buffer is larger than 1 byte, the value will reside in the upper byte of the buffer.

flags The flags structure contains the following members:
memio Indication of the type of read operation to perform.
PDIAG_IO_OP For I/O read operations.
PDIAG_MEM_OP For memory read operations..
PDIAG_POS_OP For I/O Configuration Space read operations.
count Number of accesses to perform.
PDIAG_IO_OP Number of read operations to be performed.
PDIAG_MEM_OP Number of times data is read.
PDIAG_POS_OP Count should be set to 1.
addr_incr_flag Determines whether the data buffer address and the offset address get incremented on each of count accesses:
PDIAG_SING_LOC_ACC Single-location accesses: neither address is incremented.
PDIAG_SING_LOC_BUF Single-location access for buffer: the data address is never incremented. The address referred to by offset is incremented by type.
PDIAG_SING_LOC_HW Single-location access for hardware: the data address is incremented by type. The address referred to by offset is not incremented.
PDIAG_MULT_LOC_ACC Multiple-location accesses: both addresses are incremented by type.
intrlev Indicates which environment the calling routine is in:
PROCLEV If calling from the process level
INTRKMEM If calling from the interrupt level and the data buffer is in kernel memory.
times Points to the timestruc_t structure which returns timing information. If times is a null pointer, no timing information will be returned back to the user.

Return Value

The pdiag_dd_read function returns one of the following values:

DGX_OK The operation was successful. The errno is not set.
DGX_INVALID_HANDLE Specified handle has been closed or was not generated by the pdiag_open() call. The errno is not set.
DGX_BOUND_FAIL offset given was larger than the width of the I/O address range. The errno is not set.
DGX_BADVAL_FAIL Type field was not valid (that is, not IOCHAR, IOSHORT, or IOLONG). The errno is not set.
DGX_FAIL Error occurred during the I/O read access. The errno is set to BUS_GET(L/S/C)X macro return code.
DGX_COPY_FAIL User data buffer could not be copied to or from kernel memory. The errno is set to the xmemin/out or copyin/out return code.

Related Information

pdiag_dd_write() function.

[ Previous | Next | Contents | Home | Search ]