xPCI-3009 API
PCI-3009 initialisation functions

Functions

_INT_ i_PCI3009_GetDeviceDriverVersion (IN DWORD_ dw_DeviceHandle, OUT DWORD *pdw_Version)
 
_INT_ i_PCI3009_GetDLLVersion (OUT DWORD *pdw_Version)
 
_INT_ i_PCI3009_GetNumberOfBoards (OUT BYTE *pb_NbrOfBoards)
 
_INT_ i_PCI3009_OpenBoardViaIndex (IN BYTE b_BoardIndex, OUT DWORD *pdw_BoardHandle)
 
_INT_ i_PCI3009_OpenBoardViaIdentifer (PCHAR_ pc_Identification, PDWORD_ pdw_BoardHandle)
 
_INT_ i_PCI3009_CheckAndGetPCISlotNumber (PDWORD_ pdw_SlotNumberArray)
 
_INT_ i_PCI3009_OpenBoardViaSlotNumber (DWORD_ dw_SlotNumber, PDWORD_ pdw_BoardHandle)
 
_INT_ i_PCI3009_GetBoardInformation (IN BYTE b_BoardIndex, IN DWORD dw_IdentifierStringSize, OUT CHAR *pc_Identifier, OUT DWORD *pdw_UINumber, OUT DWORD *pdw_DeviceNumber, OUT DWORD *pdw_BusNumber, OUT DWORD *pdw_BaseAddress0, OUT DWORD *pdw_BaseAddress1, OUT DWORD *pdw_BaseAddress2, OUT DWORD *pdw_BaseAddress3, OUT BYTE *pb_Interrupt, OUT DWORD *pdw_ModuleConfiguration, OUT DWORD *pdw_Revision)
 
_INT_ i_PCI3009_SetBoardIntRoutine (DWORD_ dw_BoardHandle, DWORD_ dw_UserCallingMode, DWORD_ dw_GlobalBufferSize, VOID **ppv_UserBufferRing0, VOID **ppv_UserBufferRing3, void(pascal *v_FunctionName)(DWORD_dw_BoardHandle, DWORD_dw_InterruptSrc, DWORD_dw_InterruptMask, PDWORD_ pdw_Value, DWORD_dw_UserCallingMode, VOID *pv_UserSharedMemory))
 
_INT_ i_PCI3009_SetBoardIntRoutineNew (DWORD_ dw_BoardHandle, void(pascal *v_FunctionName)(DWORD_dw_BoardHandle, DWORD_dw_InterruptSrc, DWORD_dw_InterruptMask, PDWORD_ pdw_Value, DWORD_dw_UserCallingMode, VOID *pv_UserSharedMemory))
 
_INT_ i_PCI3009_ResetBoardIntRoutine (DWORD_ dw_BoardHandle)
 
_LONG_ l_PCI3009_ReadSequenceData (DWORD_ dw_BoardHandle, DWORD dw_size, PVOID data)
 
_INT_ i_PCI3009_CloseBoard (DWORD_ dw_BoardHandle)
 

Detailed Description

Function Documentation

_INT_ i_PCI3009_GetDeviceDriverVersion ( IN DWORD_  dw_DeviceHandle,
OUT DWORD *  pdw_Version 
)

Gets the version of the device driver.

Parameters
[in]dw_DeviceHandleHandle of the board
[out]pdw_VersionVersion. For example: 0x01011211 -> Version 1.01, December 2011
Return values
0No Error
-1Error while calling IOCTL function
_INT_ i_PCI3009_GetDLLVersion ( OUT DWORD *  pdw_Version)

Gets the version of the DLL.

Parameters
[out]pdw_VersionVersion. For example: 0x01010910 -> Version 1.01, September 2010
Return values
0No Error
_INT_ i_PCI3009_GetNumberOfBoards ( OUT BYTE *  pb_NbrOfBoards)

Returns the number of xPCI3009 boards present in the system.
The function fills the value pointed by pb_NbrOfBoards with the number of boards present.

Parameters
[out]pb_NbrOfBoardsValue that will be filled with the number of boards
Return values
0No error
-1Error while getting the number of boards
_INT_ i_PCI3009_OpenBoardViaIndex ( IN BYTE  b_BoardIndex,
OUT DWORD *  pdw_BoardHandle 
)

Opens the board with the specified index. A handle is returned to the
user which allows driver functions to be used.

Parameters
[in]b_BoardIndexIndex of the board to open
[out]pdw_BoardHandleHandle of board PCI-3009
Return values
0No error
-1Unable to get the number of available boards
-2Wrong device index parameter, the parameter is too high
-3Error while getting the device's class
-4Error while getting informations about the device
-5Memory allocation error
-6Get device interface detail error
-7Error while creating communication handle
-8Error in the initialization callback function
_INT_ i_PCI3009_OpenBoardViaIdentifer ( PCHAR_  pc_Identification,
PDWORD_  pdw_BoardHandle 
)

Open the selected PCI3009 board

Parameters
[in]pc_Identification: Identification string of the board PCI3009
[out]pdw_BoardHandle: Handle of board PCI-3009
Return values
0No error
-1Not available identifier
-2Board not present
-3No handle is available for the board
-4Can not open the Windows kernel driver
-5Board I/O access error
_INT_ i_PCI3009_CheckAndGetPCISlotNumber ( PDWORD_  pdw_SlotNumberArray)

This function gets the slots number and return the number of boards found.

Parameters
[in]pdw_SlotNumberArray: Array containing the slots number of the board
Return values
0No board found
>0Number of boards
_INT_ i_PCI3009_OpenBoardViaSlotNumber ( DWORD_  dw_SlotNumber,
PDWORD_  pdw_BoardHandle 
)

This function opens the board by giving the slot number.

Parameters
[in]dw_SlotNumber: Slot number of the board
[in]pdw_BoardHandle: Handle of board PCI-3009
Return values
0No error
-1Cannot open the board
_INT_ i_PCI3009_GetBoardInformation ( IN BYTE  b_BoardIndex,
IN DWORD  dw_IdentifierStringSize,
OUT CHAR *  pc_Identifier,
OUT DWORD *  pdw_UINumber,
OUT DWORD *  pdw_DeviceNumber,
OUT DWORD *  pdw_BusNumber,
OUT DWORD *  pdw_BaseAddress0,
OUT DWORD *  pdw_BaseAddress1,
OUT DWORD *  pdw_BaseAddress2,
OUT DWORD *  pdw_BaseAddress3,
OUT BYTE *  pb_Interrupt,
OUT DWORD *  pdw_ModuleConfiguration,
OUT DWORD *  pdw_Revision 
)

Gets generic device information.

Parameters
[in]b_BoardIndexIndex of the board
[in]dw_IdentifierStringSizeSize of the identifier parameter buffer
[out]pc_IdentifierIdentifier of the board
[out]pdw_UINumberThis number is typically a user-perceived slot number, such as a number printed next to the slot on the board, or some other number that makes locating the physical device easier for the user. If the device is on a bus that has no UI number convention, or if the bus driver for the device cannot determine the UI number, this value is 0xFFFFFFFF.
[out]pdw_DeviceNumberDevice number.
[out]pdw_BusNumberBus number.
[out]pdw_BaseAddress0Base address 0 of the board
[out]pdw_BaseAddress1Base address 1 of the board
[out]pdw_BaseAddress2Base address 2 of the board
[out]pdw_BaseAddress3Base address 3 of the board
[out]pb_InterruptInterrupt line of the board
[out]pdw_ModuleConfigurationModule configuration, can be :
  • Module version in 2 ASCII characters (example 0x3132 = 12)
    • bits 0-7 second ASCII digit
    • bits 8-15 first ASCII digit
  • Module functionality
    • 0x5343 : Incremental counter
    • 0x5349 : SSI
    • 0x4449 : Digital IO
    • 0x4348 : SSI
[out]pdw_RevisionRevision of the board in ASCII
  • bits 0-7 : fourth character
  • bits 8-15 : third character
  • bits 16-23 : second character
  • bits 24-31 : first character
Return values
0No error
-1Unable to open the board via index
-2Error when calling driver's IOCTL
_INT_ i_PCI3009_SetBoardIntRoutine ( DWORD_  dw_BoardHandle,
DWORD_  dw_UserCallingMode,
DWORD_  dw_GlobalBufferSize,
VOID **  ppv_UserBufferRing0,
VOID **  ppv_UserBufferRing3,
void(pascal *v_FunctionName)(DWORD_dw_BoardHandle, DWORD_dw_InterruptSrc, DWORD_dw_InterruptMask, PDWORD_ pdw_Value, DWORD_dw_UserCallingMode, VOID *pv_UserSharedMemory)   
)

This function must be called up for each xPCI-3009 on which an interrupt action is to be enabled.
IMPORTANT: i_PCI3009_SetBoardIntRoutineNew function has to be used instead of i_PCI3009_SetBoardIntRoutine. i_PCI3009_SetBoardIntRoutine is implemented for backward compatibility reason.
It installs an user interrupt function in all boards on which an interrupt is to be enabled.
First calling (first board):

  • the user interrupt routine is installed
  • interrupts are enabled.
    If you operate several boards xPCI-3009 which have to react to interrupts, call up the function as often
    as you operate boards xPCI-3009.
    The variables v_FunctionName and dw_UserCallingMode is only relevant for the first calling.
    From the second call of the function (next board):

Interrupts are enabled. The first board can receive IRQ.

The user interrupt routine must have the following Syntax:
void WINAPI v_FunctionName (DWORD_ dw_BoardHandle,
DWORD_ dw_InterruptSrc,
DWORD_ dw_InterruptMask,
PDWORD_ pdw_Value,
DWORD_ dw_UserCallingMode,
VOID * pv_UserSharedMemory)

v_FunctionName Name of the user interrupt routine
dw_BoardHandle Handle of the xPCI-3009 which has generated the interrupt
dw_InterruptSrc Interrupt source (0: Analog input / 1: Incremental counter)
dw_InterruptMask Mask of the events which have generated the interrupt.
pdw_Value Interrupt value

dw_InterruptSrc dw_InterruptMask Meaning / pdw_Value
0 (Analog input) 1Hex Single acquisition interrupt (i_PCI3009_AnalogInputRead1Channel or i_PCI3009_AnalogInputReadMoreChannels)
pdw_Value[0] : Number of acquisitions
pdw_Value[1] : First channel value
...
pdw_Value[pdw_Value [0] - 1] : Last channel value
0 (Analog input) 2Hex Sequence acquisition interrupt without DMA (i_PCI3009_AnalogInputStartSequence)
pdw_Value[0] : Number of acquisitions (Sequence size)
pdw_Value[1] : First sequence channel value
...
pdw_Value [pdw_Value [0] - 1] : Last sequence channel value
0 (Analog input) 4Hex Sequence acquisition interrupt with DMA (i_PCI3009_AnalogInputStartSequence)
pdw_Value[0] = Number of buffer
pdw_Value[1] = Number of digital values for the buffer 0
pdw_Value[2] = Buffer 0 ring 0 address
pdw_Value[3] = Buffer 0 ring 3 address
pdw_Value[4] = Number of digital values for the buffer 1
pdw_Value[5] = Buffer 1 ring 0 address
pdw_Value[6] = Buffer 1 ring 3 address
...
1 (Incremental counter) 1Hex Hardware latch of the 1. register (High level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 10001Hex Hardware latch of the 1. register (Low level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 2Hex Hardware latch of the 2. register (High level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 10002Hex Hardware latch of the 2. register (Low level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 4Hex Index interrupt (High level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 10004Hex Index interrupt (Low level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 8Hex Compare interrupt
1 (Incremental counter) 10Hex Interrupt at the end of frequency measurement
pdw_Value[0] = Measured value
2 (Chronos) 1Hex Interrupt at the end of chronos measurement
pdw_Value[0] = Measured value
4 (Timer/counter/watchdog) 1Hex Timer 0 run down
4 (Timer/counter/watchdog) 2Hex Counter 0 run down
4 (Timer/counter/watchdog) 8Hex Timer 1 run down
4 (Timer/counter/watchdog) 10Hex Counter 1 run down
4 (Timer/counter/watchdog) 20Hex Watchdog 1 (analog output) run down
4 (Timer/counter/watchdog) 40Hex Timer 2 run down
4 (Timer/counter/watchdog) 80Hex Counter 2 run down
4 (Timer/counter/watchdog) 100Hex Watchdog 2 (digital output) run down
5 (FIFO information) 1Hex Driver interrupt FIFO overflow *


Parameters
[in]dw_BoardHandle: Handle of board PCI-3009
[in]dw_UserCallingMode: Always set on PCI3009_ASYNCHRONOUS_MODE, backward compatibility parameter.
When used for backward compatibility PCI3009_ASYNCHRONOUS_MODE or PCI3009_SYNCHRONOUS_MODE
can be set but, internally asynchronous is used.
[in]dw_GlobalBufferSize: Not to be used, backward compatibility parameter.
[out]ppv_UserBufferRing0: Not to be used, backward compatibility parameter.
[out]ppv_UserBufferRing3: Not to be used, backward compatibility parameter.
Returns
0: No error
-1: The handle parameter of the board is wrong
-2: Function call level error
-3: Wrong calling mode
-4: Interrupt function already installed for this board
-5: Interrupt installation error
_INT_ i_PCI3009_SetBoardIntRoutineNew ( DWORD_  dw_BoardHandle,
void(pascal *v_FunctionName)(DWORD_dw_BoardHandle, DWORD_dw_InterruptSrc, DWORD_dw_InterruptMask, PDWORD_ pdw_Value, DWORD_dw_UserCallingMode, VOID *pv_UserSharedMemory)   
)

This function must be called up for each xPCI-3009 on which an interrupt action is to be enabled.
IMPORTANT: i_PCI3009_SetBoardIntRoutineNew function has to be used instead of i_PCI3009_SetBoardIntRoutine. i_PCI3009_SetBoardIntRoutine is implemented for backward compatibility reason.
It installs a user interrupt function for all boards on which an interrupt is to be enabled.
First calling (first board):

  • the user interrupt routine is installed
  • interrupts are enabled.
    If you operate several boards xPCI-3009 which have to react to interrupts, call up the function as often
    as you operate boards xPCI-3009.
    The variables v_FunctionName for the first calling.
    From the second call of the function (next board):

Interrupts are enabled. The first board can receive IRQ.
To read the interrupt values when using the sequence DMA mode, use the l_CPCI3009_ReadSequenceData function.

The user interrupt routine must have the following Syntax:
void WINAPI v_FunctionName (DWORD_ dw_BoardHandle,
DWORD_ dw_InterruptSrc,
DWORD_ dw_InterruptMask,
PDWORD_ pdw_Value,
DWORD_ dw_UserCallingMode,
VOID * pv_UserSharedMemory)

v_FunctionName Name of the user interrupt routine
dw_BoardHandle Handle of the xPCI-3009 which has generated the interrupt
dw_InterruptSrc Interrupt source (0: Analog input / 1: Incremental counter)
dw_InterruptMask Mask of the events which have generated the interrupt.
pdw_Value Interrupt value

dw_InterruptSrc dw_InterruptMask Meaning / pdw_Value
0 (Analog input) 1Hex Single acquisition interrupt (i_PCI3009_AnalogInputRead1Channel or i_PCI3009_AnalogInputReadMoreChannels)
pdw_Value[0] : Number of acquisitions
pdw_Value[1] : First channel value
...
pdw_Value[pdw_Value [0] - 1] : Last channel value
0 (Analog input) 2Hex Sequence acquisition interrupt without DMA (i_PCI3009_AnalogInputStartSequence)
pdw_Value[0] : Number of acquisitions (Sequence size)
pdw_Value[1] : First sequence channel value
...
pdw_Value [pdw_Value [0] - 1] : Last sequence channel value
0 (Analog input) 4Hex Sequence acquisition interrupt with DMA (i_PCI3009_AnalogInputStartSequence)
Use l_CPCI3009_ReadSequenceData to read the channels values.
l_CPCI3009_ReadSequenceData Size of data to read should be ( sequence size * sequence before interrupt ) * sizeof ( USHORT )
1 (Incremental counter) 1Hex Hardware latch of the 1. register (High level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 10001Hex Hardware latch of the 1. register (Low level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 2Hex Hardware latch of the 2. register (High level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 10002Hex Hardware latch of the 2. register (Low level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 4Hex Index interrupt (High level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 10004Hex Index interrupt (Low level)
pdw_Value[0] = Latched counter value
1 (Incremental counter) 8Hex Compare interrupt
1 (Incremental counter) 10Hex Interrupt at the end of frequency measurement
pdw_Value[0] = Measured value
2 (Chronos) 1Hex Interrupt at the end of chronos measurement
pdw_Value[0] = Measured value
4 (Timer/counter/watchdog) 1Hex Timer 0 run down
4 (Timer/counter/watchdog) 2Hex Counter 0 run down
4 (Timer/counter/watchdog) 8Hex Timer 1 run down
4 (Timer/counter/watchdog) 10Hex Counter 1 run down
4 (Timer/counter/watchdog) 20Hex Watchdog 1 (analog output) run down
4 (Timer/counter/watchdog) 40Hex Timer 2 run down
4 (Timer/counter/watchdog) 80Hex Counter 2 run down
4 (Timer/counter/watchdog) 100Hex Watchdog 2 (digital output) run down


Parameters
[in]dw_BoardHandle: Handle of board PCI-3009
Returns
0: No error
-1: The handle parameter of the board is wrong
-4: Interrupt function already installed for this board
-5: Interrupt installation error
_INT_ i_PCI3009_ResetBoardIntRoutine ( DWORD_  dw_BoardHandle)

Stops the interrupt administration of the xPCI-3009.
Deinstalls the interrupt routine if the interrupt administration of all xPCI-3009 is stopped.

Parameters
[in]dw_BoardHandle: Handle of board PCI-3009
Returns
0: No error
-1: The handle parameter of the board is wrong
-2: Function call level error
-3: Interrupt function nor installed for this board
_LONG_ l_PCI3009_ReadSequenceData ( DWORD_  dw_BoardHandle,
DWORD  dw_size,
PVOID  data 
)

Read data acquired by a sequence acquisition.
This function can be called in the interrupt routine that you registered. (see samples)

Parameters
[out]dw_BoardHandle: Handle to the board
[in]dw_size: Size of data to read. To be powerfull, should be ( sequence size * sequence before interrupt ) * sizeof ( USHORT )
Returns
>= 0: size of data read
-1 : error while reading
_INT_ i_PCI3009_CloseBoard ( DWORD_  dw_BoardHandle)

Releases the handle of the board.Blocks the access to the board.

IMPORTANT!
Call up this function each time when you want to leave the user program!

Parameters
[in]dw_BoardHandle: Handle of board PCI-3009
Returns
0: No error
-1: The handle parameter of the board is wrong