Spectrum M2p.59 Series, Руководство по оборудованию, Страница: 50 / 190

50 (c) Spectrum Instrumentation GmbH
Driver functions Software
programs or compilers that don’t support 64 bit integer variables there are two functions that are limited to 32 bit integer variables. In case
that you do not access registers that exceed 32 bit integer please use the _i32 function. In case that you access a register which exceeds 64
bit value please use the _i64m calling convention. Inhere the 64 bit value is split into a low double word part and a high double word part.
Please be sure to fill both parts with valid information.
If accessing 64 bit registers with 32 bit functions the behavior differs depending on the real value that is currently located in the register.
Please have a look at this table to see the different reactions depending on the size of the register:
Function spcm_dwGetContBuf
This function reads out the internal continuous memory buffer in bytes, in case one has been allocated. If no buffer has been allocated the
function returns a size of zero and a NULL pointer. You may use this buffer for data transfers. As the buffer is continuously allocated in memory
the data transfer will speed up by up to 15% - 25%, depending on your specific kind of card. Please see further details in the appendix of
this manual.
These functions have been added in driver version 1.36. The functions are not available in older driver ver -
sions.
These functions also only have effect on locally installed cards and are neither useful nor usable with any
digitizerNETBOX or generatorNETBOX products, because no local kernel driver is involved in such a setup.
For remote devices these functions will return a NULL pointer for the buffer and 0 Bytes in length.
Function spcm_dwDefTransfer
The spcm_dwDefTransfer function defines a buffer for a following data transfer. This function only defines the buffer, there is no data transfer
performed when calling this function. Instead the data transfer is started with separate register commands that are documented in a later
chapter. At this position there is also a detailed description of the function parameters.
Please make sure that all parameters of this function match. It is especially necessary that the buffer address is a valid address pointing to
memory buffer that has at least the size that is defined in the function call. Please be informed that calling this function with non valid param -
eters may crash your system as these values are base for following DMA transfers.
The use of this function is described in greater detail in a later chapter.
Table 7: Spectrum driver API functions overview and differentiation between 32 bit and 64 bit registers
Internal register read/write Function type Behavior
32 bit register read spcm_dwGetParam_i32 value is returned as 32 bit integer in plValue
32 bit register read spcm_dwGetParam_i64 value is returned as 64 bit integer in pllValue
32 bit register read spcm_dwGetParam_i64m value is returned as 64 bit integer, the lower part in plValueLow, the upper part in plValueHigh. The upper part can
be ignored as it’s only a sign extension
32 bit register write spcm_dwSetParam_i32 32 bit value can be directly written
32 bit register write spcm_dwSetParam_i64 64 bit value can be directly written, please be sure not to exceed the valid register value range
32 bit register write spcm_dwSetParam_i64m 32 bit value is written as llValueLow, the value llValueHigh needs to contain the sign extension of this value. In case
of llValueLow being a value >= 0 llValueHigh can be 0, in case of llValueLow being a value < 0, llValueHigh has to
be -1.
64 bit register read spcm_dwGetParam_i32 If the internal register has a value that is inside the 32 bit integer range (-2G up to (2G - 1)) the value is returned
normally. If the internal register exceeds this size an error code ERR_EXCEEDSINT32 is returned. As an example:
reading back the installed memory will work as long as this memory is < 2 GByte. If the installed memory is >= 2
GByte the function will return an error.
64 bit register read spcm_dwGetParam_i64 value is returned as 64 bit integer value in pllValue independent of the value of the internal register.
64 bit register read spcm_dwGetParam_i64m the internal value is split into a low and a high part. As long as the internal value is within the 32 bit range, the low
part plValueLow contains the 32 bit value and the upper part plValueHigh can be ignored. If the internal value
exceeds the 32 bit range it is absolutely necessary to take both value parts into account.
64 bit register write spcm_dwSetParam_i32 the value to be written is limited to 32 bit range. If a value higher than the 32 bit range should be written, one of
the other function types need to used.
64 bit register write spcm_dwSetParam_i64 the value has to be split into two parts. Be sure to fill the upper part lValueHigh with the correct sign extension even
if you only write a 32 bit value as the driver every time interprets both parts of the function call.
64 bit register write spcm_dwSetParam_i64m the value can be written directly independent of the size.
uint32 _stdcall spcm_dwGetContBuf_i64 ( // Return value is an error code
drv_handle hDevice, // handle to an already opened device
uint32 dwBufType, // type of the buffer to read as listed above under SPCM_BUF_XXXX
void** ppvDataBuffer, // address of available data buffer
uint64* pqwContBufLen); // length of available continuous buffer
uint32 _stdcall spcm_dwGetContBuf_i64m (// Return value is an error code
drv_handle hDevice, // handle to an already opened device
uint32 dwBufType, // type of the buffer to read as listed above under SPCM_BUF_XXXX
void** ppvDataBuffer, // address of available data buffer
uint32* pdwContBufLenH, // high part of length of available continuous buffer
uint32* pdwContBufLenL); // low part of length of available continuous buffer