viMapAddress/viMapAddressEx
Purpose
Maps the specified memory space into the process's address space.
C Syntax
ViStatus viMapAddress(ViSession vi, ViUInt16 mapSpace, ViBusAddress mapBase, ViBusSize mapSize, ViBoolean access, ViAddr suggested, ViPAddr address)
ViStatus viMapAddressEx(ViSession vi, ViUInt16 mapSpace, ViBusAddress64 mapBase, ViBusSize mapSize, ViBoolean access, ViAddr suggested, ViPAddr address)
Visual Basic Syntax
viMapAddress&(ByVal vi&, ByVal mapSpace%, ByVal mapBase&, ByVal mapSize&, ByVal access%, ByVal suggested&, address&)
Resource Classes
FireWire INSTR, GPIB-VXI INSTR, GPIB-VXI MEMACC, PXI INSTR, PXI MEMACC, VXI INSTR, VXI MEMACC
Parameters
| Name | Direction | Description |
|---|---|---|
|
vi |
IN |
Unique logical identifier to a session. |
|
mapSpace |
IN |
Specifies the address space to map. Refer to the Description section for more information. |
|
mapBase |
IN |
Offset (in bytes) of the memory to be mapped. Refer to the Description section for more information. For viMapAddress(), this is a 32-bit value for 32-bit applications and a 64-bit value for 64-bit applications. For viMapAddressEx(), this is always a 64-bit value. |
|
mapSize |
IN |
Amount of memory to map (in bytes). |
|
access |
IN |
VI_FALSE (0). |
|
suggested |
IN |
If suggested parameter is not VI_NULL (0), the operating system attempts to map the memory to the address specified in suggested. There is no guarantee, however, that the memory will be mapped to that address. This operation may map the memory into an address region different from suggested. |
|
address |
OUT |
Address in your process space where the memory was mapped. |
Return Values
| Completion Codes | Description |
|---|---|
|
VI_SUCCESS |
Mapping successful. |
| 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_INV_SPACE |
Invalid address space specified. |
|
VI_ERROR_INV_OFFSET |
Invalid offset specified. |
|
VI_ERROR_NSUP_OFFSET |
Specified region is not accessible from this hardware. |
|
VI_ERROR_TMO |
viMapAddress() could not acquire resource or perform mapping before the timer expired. |
|
VI_ERROR_INV_SIZE |
Invalid size of window specified. |
|
VI_ERROR_ALLOC |
Unable to allocate window of at least the requested size. |
|
VI_ERROR_INV_ACC_MODE |
Invalid access mode. |
|
VI_ERROR_WINDOW_MAPPED |
The specified session already contains a mapped window. |
|
VI_ERROR_INV_SETUP |
Unable to start operation because setup is invalid (due to attributes being set to an inconsistent state). |
Description
The viMapAddress() operation maps in a specified memory space. The memory space that is mapped is dependent on the type of interface specified by the vi parameter and the mapSpace parameter. The address parameter returns the address in your process space where memory is mapped. The following table lists the valid entries for the mapSpace parameter.
| Value | Description |
|---|---|
|
VXI, VME, and GPIB-VXI |
VI_A16_SPACE (1) |
|
PXI INSTR |
VI_PXI_CFG_SPACE (10) |
|
PXI MEMACC |
VI_PXI_ALLOC_SPACE (9) |
|
FireWire INSTR |
VI_FIREWIRE_DFLT_SPACE (5) |
 |
Note On some hardware platforms, the low-level driver may have limitations on the parameters to this function. For example, on VXI resources mapBase should be a multiple of mapSize for best results. If these limitations prevent NI-VISA from mapping the full region you request (mapSize bytes starting at mapBase), the function will return an error such as VI_ERROR_NSUP_OFFSET or VI_ERROR_ALLOC. |
INSTR Specific
Notice that mapBase specified in the viMapAddress() operation for an INSTR Resource is the offset address relative to the device's allocated address base for the corresponding address space that was specified. For example, if mapSpace specifies VI_A16_SPACE, then mapBase specifies the offset from the logical address base address of the specified VXI device. If mapSpace specifies VI_A24_SPACE or VI_A32_SPACE, then mapBase specifies the offset from the base address of the VXI device's memory space allocated by the VXI Resource Manager within VXI A24 or A32 space.
To specify the full 48-bit offset for these methods on a FireWire INSTR session, a call to viSetAttribute using VI_ATTR_FIREWIRE_WIN_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
For a MEMACC Resource, the mapBase parameter specifies an absolute address.
|
Note The output address is not necessarily always a pointer. It may be possible for viMapAddress to succeed and output a token address value of 0. This is not the same as a NULL pointer, even though the value of NULL is 0. Obviously, this situation cannot happen if the address is a pointer that the user can dereference. Regardless, you should determine whether viMapAddress succeeded or failed by checking the returned status, not the output value of the address. |
Related Topics