 |
Index for
Section 3 |
|
 |
Alphabetical
listing for I |
|
 |
Bottom of
page |
|
imc_bcopy(3)
NAME
imc_bcopy - Efficient data copy to a Memory Channel transmit region
LIBRARY
Memory Channel API library (libimc.a)
SYNOPSIS
#include <sys/imc.h>
long imc_bcopy (
void *src,
void *dest,
long length,
long dest_write_only,
long first_dest_quad);
PARAMETERS
src Points to the source data buffer for the imc_bcopy() function.
dest Points to the destination data buffer for the imc_bcopy()
function.
length Specifies the length, in bytes, of the original data buffer.
dest_write_only
Specifies whether the destination is a write-only pointer.
first_dest_quad
Specifies the contents of the first quadword of the destination.
DESCRIPTION
The imc_bcopy() function copies length bytes from the buffer pointed to by
the src parameter into the buffer pointed to by the dest parameter.
The imc_bcopy() function is highly optimized for the Alpha architecture and
implements an extremely efficient copy operation. You can use the
imc_bcopy() function for a high-bandwidth copy between two buffers in
normal memory, as well as for copying to Memory Channel transmit addresses,
regardless of buffer alignment or data length.
A Memory Channel region may be attached for transmit (that is, for write)
using the imc_asattach() function or the imc_asattach_ptp() function. The
address for such a region is write-only, and any attempt to read from a
transmit address will result in a segmentation violation. In addition,
segmentation violations will result from any operation that causes the
compiler to generate read-modify-write cycles. For example:
· Assignment to simple data types that are not an integral multiple of
four bytes.
· Use of the bcopy(3) function where the length parameter is not an
integral multiple of eight bytes, or where the source or destination
arguments are not eight-byte aligned.
The imc_bcopy() function is designed to be used instead of the bcopy(3)
function in such cases, as its src parameter and its dest parameter can
both have an arbitrary alignment.
If the value of the dest_write_only parameter is zero (0), unaligned writes
to the dest address can cause the quadwords containing the first and last
destination bytes to be read.
If the value of the dest_write_only parameter is nonzero, as it would be
for Memory Channel transmit addresses, the first_dest_quad parameter value
is used as the contents of the first quadword of the destination, and zero
(0) is used as the contents of the last quadword of the destination. If
the caller does not know the contents of the first quadword of the
destination, use zero (0) as the value of the first_dest_quad parameter.
This will result in up to three bytes of zeros before the start of the
copied data, and up to three bytes of zeros after the end of the copied
data.
The imc_bcopy() function returns the last quadword written to the
destination. You can use this capability to concatenate several
noncontiguous buffers to a contiguous write-only destination. To perform
this operation, known as a gather operation, use the return value from one
call to the imc_bcopy() function as the first_dest_quad parameter for the
next call to the imc_bcopy() function. If you are not performing a gather
operation, that is, if the start of the dest parameter is not in same
quadword as the previous end of the dest parameter, then the value of the
first_dest_quad parameter should be zero.
RESTRICTIONS
If the source and destination buffers overlap, the result of the copy
operation is undefined.
EXAMPLES
1. This example shows how to use the imc_bcopy() function to copy between
two buffers that have arbitrary alignment. The destination buffer is
not a Memory Channel transmit address. In this example, 25 bytes are
copied from an aligned source to a destination that is not aligned on
a quadword boundary.
int source[256];
char destination[1024];
long last_quad;
/* fill in source buffer */
/* copy part of source buffer */
last_quad = imc_bcopy(source,destination+3,25,0,0);
2. This example shows how to use the imc_bcopy() function to copy data to
a Memory Channel transmit address. In the example, 18 bytes are copied
to a Memory Channel transmit address at an offset of 12 bytes from the
beginning of the region.
int source[256];
caddr_t tx_addr;
imc_asid_t id;
int status;
int prev_err;
long last_quad;
/* allocate and attach destination buffer */
status = imc_api_init(NULL);
if (status != IMC_SUCCESS)
imc_perror("imc_api_init",status);
/* allocate a region of size 8K using key 678 on logical rail zero
*/
status = imc_asalloc(678,8192,IMC_URW,0,&id,0);
if (status != IMC_SUCCESS)
imc_perror("imc_asalloc",status);
/* attach for transmit without LOOPBACK */
status = imc_asattach(id,IMC_TRANSMIT,IMC_SHARED,0,&tx_addr);
if (status != IMC_SUCCESS)
imc_perror("imc_asattach",status);
/* fill in source buffer */
/* copy part of the source buffer and check for errors */
do {
prev_err = imc_rderrcnt_mr(0);
last_quad = imc_bcopy(source,tx_addr+12,18,1,0);
} while ((status = imc_ckerrcnt_mr(&prev_err,0)) != IMC_SUCCESS);
3. This example shows how to use the imc_bcopy() function to copy data to
a Memory Channel transmit address from several sources. The sources
may be noncontiguous.
int *src1;
long *src2;
char *src3;
long len1,len2,len3;
caddr_t tx_addr;
int status;
int prev_err;
long last_quad;
/* allocate and attach destination buffer */
/* assign and fill source buffers and their lengths */
/* append the source buffers at their destination */
do {
prev_err = imc_rderrcnt_mr(0);
last_quad = imc_bcopy(src1,tx_addr,len1,1,0);
last_quad = imc_bcopy(src2,tx_addr+len1,len2,1,last_quad);
last_quad = imc_bcopy(src3,tx_addr+len1+len2,len3,1,
last_quad);
} while ((status = imc_ckerrcnt_mr(&prev_err,0)) != IMC_SUCCESS);
RETURN VALUES
The imc_bcopy() function returns the last quadword written to the
destination buffer.
RELATED INFORMATION
Introduction: imc(3)
Commands: imc_init(1), imcs(1)
Functions: imc_asalloc(3), imc_asattach(3), imc_asattach_ptp(3)
Cluster Highly Available Applications
|
Index for
Section 3 |
|
|
Alphabetical
listing for I |
|
 |
Top of
page |
|