'\" te
.\"  Copyright (c) 1996, Sun Microsystems, Inc  All Rights Reserved
.TH ddi_device_copy 9F "15 Nov 1996" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
ddi_device_copy \- copy data from one device register to another device register
.SH SYNOPSIS
.LP
.nf
#include <sys/ddi.h> 
#include <sys/sunddi.h>

\fBint\fR \fBddi_device_copy\fR(\fBddi_acc_handle_t\fR \fIsrc_handle\fR, \fBcaddr_t\fR \fIsrc_addr\fR, 
     \fBssize_t\fR \fIsrc_advcnt\fR, \fBddi_acc_handle_t\fR \fIdest_handle\fR,
     \fBcaddr_t\fR \fIdest_addr\fR, \fBssize_t\fR \fIdest_advcnt\fR, 
     \fBsize_t\fR \fIbytecount\fR, \fBuint_t\fR \fIdev_datasz\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI).
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIsrc_handle\fR \fR
.ad
.RS 16n
.rt  
The data access handle of the source device.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsrc_addr\fR \fR
.ad
.RS 16n
.rt  
Base data source address.
.RE

.sp
.ne 2
.mk
.na
\fB\fIsrc_advcnt\fR \fR
.ad
.RS 16n
.rt  
Number of  \fIdev_datasz\fR units to advance on every access.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdest_handle\fR \fR
.ad
.RS 16n
.rt  
The data access handle of the destination device.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdest_addr\fR \fR
.ad
.RS 16n
.rt  
Base data destination address.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdest_advcnt\fR \fR
.ad
.RS 16n
.rt  
Number of  \fIdev_datasz\fR units to advance on every access.
.RE

.sp
.ne 2
.mk
.na
\fB\fIbytecount\fR \fR
.ad
.RS 16n
.rt  
Number of bytes to transfer.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdev_datasz\fR \fR
.ad
.RS 16n
.rt  
The size of each data word. Possible values are defined as: 
.sp
.ne 2
.mk
.na
\fB\fBDDI_DATA_SZ01_ACC\fR \fR
.ad
.RS 22n
.rt  
1 byte data size
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_DATA_SZ02_ACC\fR \fR
.ad
.RS 22n
.rt  
2 bytes data size
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_DATA_SZ04_ACC\fR \fR
.ad
.RS 22n
.rt  
4 bytes data size
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_DATA_SZ08_ACC\fR \fR
.ad
.RS 22n
.rt  
8 bytes data size
.RE

.RE

.SH DESCRIPTION
.sp
.LP
\fBddi_device_copy()\fR copies  \fIbytecount\fR bytes from the source  address,  \fIsrc_addr\fR, to the destination address,  \fIdest_addr\fR. The attributes encoded in the access handles, \fIsrc_handle\fR and \fIdest_handle\fR, govern how data is actually copied from the  source to the destination. Only matching data sizes between the source and destination are supported.
.sp
.LP
Data will automatically be translated to maintain a consistent  view between the source and the destination. The translation may  involve byte-swapping if the source and the destination devices  have incompatible endian characteristics.
.sp
.LP
The  \fIsrc_advcnt\fR and  \fIdest_advcnt\fR arguments specifies the number of  \fIdev_datasz\fR units to advance with each access to the device addresses. A value of  \fB0\fR will use the same source and destination device address  on every access. A positive value increments the corresponding device  address by certain number of data size units in the next access.  On the other hand, a negative value decrements the device address.
.sp
.LP
The \fIdev_datasz\fR argument determines the size of the data word on each access. The data size must be the same between the source and destination.
.SH RETURN VALUES
.sp
.LP
\fBddi_device_copy()\fR returns:
.sp
.ne 2
.mk
.na
\fB\fBDDI_SUCCESS\fR \fR
.ad
.RS 16n
.rt  
Successfully transferred the data. 
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_FAILURE\fR \fR
.ad
.RS 16n
.rt  
The byte count is not a multiple \fIdev_datasz\fR. 
.RE

.SH CONTEXT
.sp
.LP
\fBddi_device_copy()\fR can be called from user, kernel, or interrupt context.
.SH SEE ALSO
.sp
.LP
\fBddi_regs_map_free\fR(9F), \fBddi_regs_map_setup\fR(9F) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR