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

pdiag_dd_write

Purpose

The pdiag_dd_write() function performs a write operation on a resource.

Syntax


#include <sys/pdiagex_dds.h>
int32 pdiag_dd_write( 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_write() function writes the specified data to the specified offset address. If the user enables the times variable, timing information for this function is also returned. Each write performed is dependent on the memio operation and count parameters.

PDIAG_IO_OP If count is1, data is written to the specified bus I/O offset address.
PDIAG_MEM_OP If count is1, data is written to the specified memory offset address.
PDIAG_POS_OP If count is1, data is written to the specified POS offset address.

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

Note: When writing data, it is imperative that the write data buffer is at least the size of count * type (unless the write data buffer address is not being incremented) and filled with valid data for each write operation to be performed. If this is not done, meaningless data is written to the designated area. This may cause problems with your testing.

Execution Environment

The pdiag_dd_write() 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 Pointer to a block of information to be written to the specified address. This block will be of size:
count for type IOCHAR8 (1 if not incrementing data)

OR

count *2 for type IOSHORT16 (2 if not incrementing data)

OR

count *4 for type IOLONG32 (4 if not incrementing data).
flags The flags structure contains the following members:
memio Indication of the type of read operation to perform.
PDIAG_IO_OP For I/O write operations.
PDIAG_MEM_OP For memory write operations.
PDIAG_POS_OP For I/O Configuration Space write operations.
count Number of accesses to perform.
PDIAG_IO_OP Number of write operations to be performed.
PDIAG_MEM_OP Number of times data is written.
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_write 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 IOCHAR8, IOSHORT16, or IOLONG32). The errno is not set.
DGX_FAIL Error occurred during the I/O write access. The errno is set to BUS_PUT(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_read() function.

[ Previous | Next | Contents | Home | Search ]