viMove/viMoveEx
Purpose
Moves a block of data.
C Syntax
ViStatus viMove(ViSession vi, ViUInt16 srcSpace, ViBusAddress srcOffset, ViUInt16 srcWidth, ViUInt16 destSpace, ViBusAddress destOffset, ViUInt16 destWidth, ViBusSize length)
ViStatus viMoveEx(ViSession vi, ViUInt16 srcSpace, ViBusAddress64 srcOffset, ViUInt16 srcWidth, ViUInt16 destSpace, ViBusAddress64 destOffset, ViUInt16 destWidth, ViBusSize length)
Visual Basic Syntax
viMove&(ByVal vi&, ByVal srcSpace%, ByVal srcOffset&, ByVal srcWidth%, ByVal destSpace%, ByVal destOffset&, ByVal destWidth%, ByVal length&)
Resource Classes
FireWire INSTR, GPIB-VXI INSTR, GPIB-VXI MEMACC, PXI INSTR, VXI INSTR, VXI MEMACC
Parameters
| Name | Direction | Description |
|---|---|---|
|
vi |
IN |
Unique logical identifier to a session. |
|
srcSpace |
IN |
Specifies the address space of the source. |
|
srcOffset |
IN |
Offset of the starting address or register from which to read. For viMove(), this is a 32-bit value for 32-bit applications and a 64-bit value for 64-bit applications. For viMoveEx(), this is always a 64-bit value. |
|
srcWidth |
IN |
Specifies the data width of the source. |
|
destSpace |
IN |
Specifies the address space of the destination. |
|
destOffset |
IN |
Offset of the starting address or register to which to write. For viMove(), this is a 32-bit value for 32-bit applications and a 64-bit value for 64-bit applications. For viMoveEx(), this is always a 64-bit value. |
|
destWidth |
IN |
Specifies the data width of the destination. |
|
length |
IN |
Number of elements to transfer, where the data width of the elements to transfer is identical to the source data width. |
Return Values
| Completion Codes | Description |
|---|---|
|
VI_SUCCESS |
Operation completed successfully. |
| Error Codes | Description |
|---|---|
|
VI_ERROR_INV_OBJECT |
The given session reference is invalid. |
|
VI_ERROR_NSUP_OPER |
The given vi does not support this operation. |
|
VI_ERROR_RSRC_LOCKED |
Specified operation could not be performed because the resource identified by vi has been locked for this kind of access. |
|
VI_ERROR_BERR |
Bus error occurred during transfer. |
|
VI_ERROR_INV_SPACE |
Invalid source or destination space specified. |
|
VI_ERROR_INV_OFFSET |
Invalid source or destination offset specified. |
|
VI_ERROR_INV_WIDTH |
Invalid source or destination width specified. |
|
VI_ERROR_NSUP_OFFSET |
Specified source or destination offset is not accessible from this hardware. |
|
VI_ERROR_NSUP_VAR_WIDTH |
Cannot support source and destination widths that are different. |
|
VI_ERROR_INV_SETUP |
Unable to start operation because setup is invalid (due to attributes being set to an inconsistent state). |
|
VI_ERROR_NSUP_WIDTH |
Specified width is not supported by this hardware. |
|
VI_ERROR_NSUP_ALIGN_OFFSET |
The specified offset is not properly aligned for the access width of the operation. |
|
VI_ERROR_INV_LENGTH |
Invalid length specified. |
Description
The viMove() and viMoveEx() operations move data from the specified source to the specified destination. The source and the destination can either be local memory or the offset of the interface with which this MEMACC Resource is associated. These operations use the specified data width and address space. In some systems, such as VXI, users can specify additional settings for the transfer, such as byte order and access privilege, by manipulating the appropriate attributes.
The following table lists the valid entries for specifying address space.
| Value | Description |
|---|---|
|
VI_A16_SPACE (1) |
Address the A16 address space of the VXI/MXI bus. |
|
VI_A24_SPACE (2) |
Address the A24 address space of the VXI/MXI bus. |
|
VI_A32_SPACE (3) |
Address the A32 address space of the VXI/MXI bus. |
|
VI_LOCAL_SPACE (0) |
Address process-local memory (using a virtual address). |
|
VI_OPAQUE_SPACE (FFFFh) |
Addresses potentially volatile data (using a virtual address). |
The following table lists the valid entries for specifying widths.
| Value | Description |
|---|---|
|
VI_WIDTH_8 (1) |
Performs 8-bit (D08) transfers. |
|
VI_WIDTH_16 (2) |
Performs 16-bit (D16) transfers. |
|
VI_WIDTH_32 (4) |
Performs 32-bit (D32) transfers. |
|
VI_WIDTH_64 (8) |
Performs 64-bit (D64) transfers. |
All VXI and PXI accesses performed by the viMove() and viMoveEx() operations use either the same or successive offsets, depending on the increment value specified by VI_ATTR_SRC_INCREMENT and VI_ATTR_DEST_INCREMENT.
If srcSpace is VI_LOCAL_SPACE, viMove() will ignore VI_ATTR_SRC_INCREMENT. If destSpace is VI_LOCAL_SPACE, viMove() will ignore VI_ATTR_DEST_INCREMENT. Local accesses always increment the offset for each index in a multi-element transfer, rather than using the increment specified by the attributes. If srcSpace is any value other than VI_LOCAL_SPACE, including VI_OPAQUE_SPACE, viMove() will honor VI_ATTR_SRC_INCREMENT. If destSpace is any value other than VI_LOCAL_SPACE, including VI_OPAQUE_SPACE, viMove() will honor VI_ATTR_DEST_INCREMENT. While VI_OPAQUE_SPACE uses a process-local virtual address, it is not necessarily pointing to system memory, so it may be a FIFO. Therefore, VI_ATTR_SRC/DEST_INCREMENT do indeed apply.
INSTR Specific
If srcSpace is neither VI_LOCAL_SPACE nor VI_OPAQUE_SPACE, srcOffset is a relative address of the device associated with the given INSTR resource. Similarly, if destspace is neither VI_LOCAL_SPACE nor VI_OPAQUE_SPACE, destOffset is a relative address of the device associated with the given INSTR resource.
The primary intended use of this operation with an INSTR session is to synchronously move data to or from the device. Therefore, either the srcSpace or destSpace parameter will usually be VI_LOCAL_SPACE.
To specify the full 48-bit offset for these methods on a FireWire INSTR session, a call to viSetAttribute using VI_ATTR_FIREWIRE_SRC_UPPER_OFFSET or VI_ATTR_FIREWIRE_DEST_UPPER_OFFSET is needed prior to calling these methods. Subsequent calls to viSetAttribute are needed only if the upper 16 bits of the FireWire offset change.
MEMACC Specific
The destOffset and srcOffset parameters specify absolute addresses. Notice also that the length specified in the viMove() and viMoveEx() operations is the number of elements (of the size corresponding to the srcWidth parameter) to transfer, beginning at the specified offsets. Therefore, srcOffset + length*srcWidth cannot exceed the total amount of memory exported by the given srcSpace. Similarly, destOffset + length*srcWidth cannot exceed the total amount of memory exported by the given destSpace.
Related Topics
VI_ATTR_FIREWIRE_DEST_UPPER_OFFSET